Messaging · The Mobility Factory Documentation

As of release Partago/5.2, a new messaging system is in place to handle all communications, i.e. email and in app chat, with the users.

This system is very general and could also be extended to define and execute other (non communication) scripted flows.

Triggers

Everything starts with triggers. Triggers are fired in the backend when some event happens, e.g. user makes a reservation. A trigger has a type and comes with some extra information describing the event that happened, e.g. the user making the reservation and the details of the reservation.

Action scripts

Whenever a trigger is fired, a number of actions are executed. The actions to be executed are configured in the database and depend on the type of the trigger and optionally the extra information.

The json below shows the structure of the configuration in the database. Under the top level field scripts, there is a field actions. This contains a map with keys the different trigger types and values, lists of actions to be executed for this trigger type. Each action has a field type, which defines the predefined action types (currently send_email, conversation and filter) and additional configuration fields.

Under the field scripts, there is also a field config, which is used to store some configurations which are shared between actions, like the configuration of the smtp server.

{
  "scripts": {
    "actions": {
      "reservation_cancel": {
        "1": {
          "type": "send_email",
          ...
        },
        "2": {
          ...
        }
      }
    },
    "config": {
      "chatters": {
        "my_chatter": {
          ...
        }
      },
      "mailers": {
        "my_mailer": {
          ...
        }
      }
    }
  }
}

`send_email` action

This action sends an email to one or more recipients.

Below is a configuration of such an action. The field recipients is a comma separated list of email addresses who should receive this email. The value can contain interpolations following the ICU syntax to replace some part with values from the triggers extra information. In the example below, the email will be sent to info@partago.be and to the email address defined in the trigger details under reservation.person.email.

{
  "type": "send_email",
  "recipients": "{reservation.person.email},info@partago.be",
  "mailer": "my_mailer",
  "template": "newReservation"
}

The field template refers to the template, containing the subject, body and optional attachments for the email. This template is defined in the resource sets (see below).

The field mailer refers to the smtp configuration to use to send the emails. This configuration is defined in scripts/config/mailers/$mailer_key and looks like:

{
  "host": "smtp-auth.mailprotect.be:2525",
  "username": "notifications@partago.be",
  "password": "secret",
  "from": "notifications@partago.be",
  "fromName": "Partago"
}

`conversation` action

This action automatically posts messages to a conversation (currently, this is the in-app-chat, but it is quite generic, so it could be extended to send to other chat apps).

Below is an example of the action configuration.

{
  "type": "conversation",
  "chatter": "my_chatter",
  "template": "newReservation"
}

The field template refers to the template, containing the different messages to be posted. This template is defined in the resource sets (see below).

The field chatter refers to the configuration to use to post messages. This configuration is defined in scripts/config/chatters/$chatter_key. Currently only one type of chatter is recognized, this is the partago_in_app. The configuration should be as follows:

{
  "type": "partago_in_app"
}

`filter` action

This action allows to set a condition for the execution of another action.

Below is an example of a configuration that will send an email only when the group id is team.

{
  "type": "filter",
  "condition": "reservation.group.id=='team'",
  "action": {
    "type": "send_email",
    "mailer": "partago",
    "template": "newReservation",
    "recipients": "{reservation.person.email}"
  }
}

List of triggers

Below is the list of triggers and their extra information.

reservation_create

Fired when a user creates a new reservation. It contains the following extra information:

key	type	description
`reservation`	`object`	information about the reservation
`transaction`	`object`	information about the transaction on the users billing account

The field reservation is a map with the following properties:

key	type	description
`id`	`string`	unique id for the reservation
`startTime`	`datetime`	the start time of the reservation
`endTime`	`datetime`	the end time of the reservation
`person`	`object`	the person who owns the reservation
`resource`	`object`	the car config for which this is a reservation
`isCancelled`	`boolean`	true if this reservation has been cancelled, null or false otherwise
`effectiveStartTime`	`datetime`	the time usage has started, null if not yet started
`effectiveEndTime`	`datetime`	the time usage has ended, null if not yet ended
`group`	`object`	the group for which this is a reservation

The field person is a map with the following properties:

key	type	description
`id`	`string`	unique id for the person
`firstname`	`string`	the person's first name
`lastname`	`string`	the person's last name
`email`	`string`	the person's email address

The field resource is a map with the following properties:

key	type	description
`id`	`string`	unique id for the car config
`name`	`string`	the name of the car config
`home`	`object`	the home location of this car config

The field group is a map with the following properties:

key	type	description
`id`	`string`	unique id for the group
`name`	`string`	the name of the group

The field home is a map with the following properties:

key	type	description
`name`	`string`	the name of this location

The field transaction is a map with the following properties:

key	type	description
`amount`	`number`	the number of credits that are added or subtracted from the billing account
`bill`	`object`	the bill details

reservation_update

Fired when a user updates an existing reservation. It contains the following extra information:

key	type	description
`reservation`	`object`	information about the reservation
`oldReservation`	`object`	information about the previous start end end time of the reservation
`transaction`	`object`	information about the transaction on the users billing account

The fields reservation and transaction have the same properties as listed above. The field oldReservation is a map with the following properties:

key	type	description
`startTime`	`datetime`	the old start time of the reservation
`endTime`	`datetime`	the old end time of the reservation

reservation_cancel

Fired when a user cancels an existing reservation. It contains the following extra information:

key	type	description
`reservation`	`object`	information about the reservation
`transaction`	`object`	information about the transaction on the users billing account

The fields reservation and transaction have the same properties as listed above.

usage_start

Fired when a user starts using a car. It contains the following extra information:

key	type	description
`reservation`	`object`	information about the reservation
`transaction`	`object`	information about the transaction on the users billing account

The fields reservation and transaction have the same properties as listed above.

usage_end

Fired when a user ends using a car. It contains the following extra information:

key	type	description
`reservation`	`object`	information about the reservation
`transaction`	`object`	information about the transaction on the users billing account

The fields reservation and transaction have the same properties as listed above.

user_register

Fired when a user requests a registration key. It contains the following extra information:

key	type	description
`person`	`object`	the person doing the request
`link`	`url`	the unique url containing the registration key, that can be used by the user to create an account

The field person has the same properties as listed above.

user_request_access

shop_buy

Resource sets

Email and conversation templates are defined in resource sets. Multiple resource sets can be defined in the database. The resource set to be used depends on the config for the person and the group that causes the trigger.

A resource set contains emailTemplates and conversationTemplates, which are maps with the name of the template as key and the template as value.

Email template

An example email template is shown below. It contains a subject field, which is either a string (ICU syntax for formatting) or a map of localized strings. The content field has the same structure, but can also contain html formatting. The attachments field is optional and can contain one or more attachments to add to the email (also ICU syntax for formatting).

{
  "subject": {
    "nl": "{reservation.resource.name} zal voor jou klaar staan op {reservation.startTime, date, long} om {reservation.startTime, time}",
    "en": "{reservation.resource.name} will be ready for you on {reservation.startTime, date, long} at {reservation.startTime, time}"
  },
  "content": {
    "nl": "Dag {reservation.person.firstname}, ...",
    "en": "Hello {reservation.person.firstname}, here you can add some html content"
  },
  "attachments": {
    "1": {
      "name": "event.ics",
      "content": "BEGIN:VCALENDAR\nVERSION:2.0\nX-WR-RELCALID:ABC\nMETHOD:REQUEST\nBEGIN:VTIMEZONE\nTZID:Europe/Berlin\nX-LIC-LOCATION:Europe/Berlin\nBEGIN:DAYLIGHT\nTZOFFSETFROM:+0100\nTZOFFSETTO:+0200\nTZNAME:CEST\nDTSTART:19700329T020000\nRRULE:FREQ=YEARLY;INTERVAL=1;BYDAY=-1SU;BYMONTH=3\nEND:DAYLIGHT\nBEGIN:STANDARD\nTZOFFSETFROM:+0200\nTZOFFSETTO:+0100\nTZNAME:CET\nDTSTART:19701025T030000\nRRULE:FREQ=YEARLY;INTERVAL=1;BYDAY=-1SU;BYMONTH=10\nEND:STANDARD\nEND:VTIMEZONE\nBEGIN:VEVENT\nUID:partago-r-{reservation.id}\nDTSTART;TZID=Europe/Berlin:{reservation.startTime, time, yyyyMMdd'T'HHmm'Z'}\nDTEND;TZID=Europe/Berlin:{reservation.endTime, time, yyyyMMdd'T'HHmm'Z'}\nLOCATION:{reservation.resource.home.name}\nORGANIZER;CN=Partago:MAILTO:info@partago.be\nSEQUENCE:0\nSTATUS:CONFIRMED\nSUMMARY:{reservation.resource.name}\nDESCRIPTION:{reservation.resource.name} has been reserved by {reservation.person.firstname} {reservation.person.lastname}\nPRIORITY:3\nBEGIN:VALARM\nACTION:DISPLAY\nDESCRIPTION:This is an event reminder\nTRIGGER:-P0DT0H10M0S\nEND:VALARM\nEND:VEVENT\nEND:VCALENDAR\n"
    }
  }
}

Conversation template

An example conversation template is shown below. It contains a list of messages to be sent. These messages can be formatted and localized the same way as with the email templates.

{
  "messages": {
    "1": {
      "author": "{reservation.person.id}",
      "text": {
        "nl": "Hoi Partago! Ik zou graag {reservation.resource.name} gebruiken ...",
        "en": "Hi Partago! I would like to use {reservation.resource.name} ..."
      }
    },
    "2": {
      "author": "Partago",
      "text": {
        "nl": "Hoi {reservation.person.firstname}! Dat kan ...",
        "en": "Hi {reservation.person.firstname}! You can ..."
      }
    }
  },
  "subject": "reservationDetails/{reservation.id}"
}

Triggers

Action scripts

send_email action

conversation action

filter action

List of triggers

reservation_create

reservation_update

reservation_cancel

usage_start

usage_end

user_register

user_request_access

shop_buy

Resource sets

Email template

Conversation template

`send_email` action

`conversation` action

`filter` action