Triggering Workflows

Workflows is the powerhouse that combines all the components together, processes them and ultimately delivers the communication to your end user.

You can have a single communication in a workflow (eg. transaction done), or a series of communications in a single workflow (eg. product recommendation series).

Once created, you can check the performance of each workflow on how they are performing (in terms of delivery rate and user interactions), for all channels at one place.

You can configure and trigger workflows from SuprSend platform, as well as from your backend via SuprSend API.

Elements in a Workflow

For constructing a workflow, you need to have following elements, each element acts as a node to workflow:

1. Trigger

A workflow needs a trigger to be executed, there can be 2 types of trigger:

• Event Based trigger: When an event is received on SuprSend, trigger the workflow for the user associated with the event will get the communication. (Eg. Notify a user when he makes a transaction)
• Time Based trigger: A particular date-time triggers the workflow, like a cron job. (Eg. Every day at 3pm send a recommendation to some users).
  

2. Override Recipient

The "Recipient" refers to either a single user or a group of users who will be receiving a notification. By default, the user who initiates the event (specified by the distinct_id parameter in the track event call) will be considered as the recipient.

However, there may be situations where you do not want the notification to be sent to the user who initiates the action. For instance, when john shares a document with olivia for review, and olivia adds comments to the document, you would want to inform john that he has received new comments on the shared document.

To handle such cases, you can override the default recipient with another identifier specified in the event property. For example if this is the event call, you can pass .recipient in the recipient field to send the notification to [email protected]

distinct_id = "0fxxx8f74-xxxx-41c5-8752-xxxcb6911fb08" # Unique id of user in your application

event_name = "product_purchased"   # name of the event you're tracking

# Properties: a dict representing event-attributes
properties = {													
  "first_name": "User",
  "spend_amount": "$10",
  "recipient":"[email protected]"
}

event = Event(distinct_id=distinct_id, event_name=event_name, properties=properties)

You can add recipient as a JQ-expression. Below are some examples of how to enter recipient in the workflow:

1. To enter an array of recipient something like "recipients": ["recipient1","recipient2","recipient3"], enter in the format .recipients[]. It would send the notification to all the recipients in the array.
2. If the recipient is a nested event property key like shown below, enter in the format .recipient.id.

properties = {													
  "recipient": {
    "name": "Steve",
    "id": "0exxx9g12-xxxx-31b5-8752-xxxcb7860fb07"
  }
}

3. In the below array object example, if you want to send notifications to all the admins of an organization, enter in the format .organization.admins[].user_id.

properties = {
  "organization":{
    "id":"1234",
    "admins": [
      {
        "user_id":"0exxx9g12-xxxx-31b5-8752-xxxcb7860fb07",
        "name":"Olivia"
      },
      {
        "user_id":"1gxxx5a32-xxxx-73b3-9854-xxxqw7891fb07",
        "name":"Steve"
      }],
    "members": [
      {
        "user_id":"4txxx9a18-xxxx-71f5-0876-xxxmn7908fb07",
        "name":"Amy"
      },
      {
        "user_id":"5yxxx0n23-xxxx-90f5-0746-xxxmn9081fb91",
        "name":"Jane"
      }
    ],
    "location":"San Francisco"
  }}

3. Delay

On having a delay, a workflow will be halted for the time mentioned in delay, and become active once the delay period is over. (Eg. Notify a user after 1 hour of making a transaction)

4. Batching Event (Digest)

Batching Event is useful when a user needs to be notified about a lot of events happening at once, but doesn't need a notification for every single event within the batch. For eg. if you have a product where users can interact with each other's content and posts 5 comments in 10 mins. In this case sending notification to user for every comment can be irritating. So rather than sending 5 notifications, you can batch the events for 10 mins and send one notification about the 5 comments that the user received.

Here's a breakdown of how batching works:

1. Batch Window :
   Batch window is the time for which your batch should be open for. After receiving the first event, the workflow will be halted for the time added in batch window and all the events coming in this window will be accumulated. The notification will be sent after the batch window is over.
   For example: If the batch window is set at 10 mins, all the comments added in the window of 10 mins will be batched and a notification will be sent to the user after 10 mins.
   
   
2. Batch Key:
   This is the property in your track event call used for batching the events. By default, event will be batched per user. For instance, if you want to batch only the comments added on a Jira task in a message and would send separate notifications for comments on different Jira cards. In this case, you can add jira_card_id as your batch key. The batching of comments will now happen for each unique user_id and jira_card_id pair
   
   
3. Using Batch variables in templates:
   There are 2 type of variables created by default for batched events:
   
   1. $batched_events array : All the event properties corresponding to a batched event is appended to this array and can be used in the template in the array format.
      
   2. $batched_event_count: This is the count of the event accumulated in any batch. For example, if 3 comments are added in the batch window of 10 mins, $batched_event_count = 3
      

Below is an example of how the variables in a batched event will look like:

{
  "$batched_events": [
    {
      "name": "Joe",
      "card_id": "SS-12",
      "comment": "Hey, added the test cases added for PRD-12"
    },
    {
      "name": "Joe",
      "card_id": "SS-12",
      "comment": "Hey, done with the testing. Check the bugs"
    },
    {
      "name": "Joe",
      "card_id": "SS-12",
      "comment": "3 bugs are resolved, 4 are still pending"
    }
  ],
  "$batched_events_count": 3
}

5. User Segment

Workflow needs to know the users to which it will deliver the communication. For a user, all the channels for which information are provided to SuprSend will become eligible for delivery .

6. Template

A workflow need to know that when it is triggered, which template has to be invoked. You can use any template which is created on SuprSend, which is in 'Active' stage. All the channels that have a live published template will be eligible for the workflow.

7. Override Channels

By default, Notification is sent to all template channels that are present in user's profile. However, You can override this behaviour using override channels field. This feature comes in handy when user channels are dynamically defined at the user level for each workflow. For instance, when booking an appointment, your users are dynamically defining their preferred channel for receiving booking updates for each appointment.

For more consistent channel preferences, like user wanting to receive all communication via email only, or notifications for a specific category (like booking updates) through Android push, and another category (like chat updates) in the Inbox, we recommend updating it using user preferences.

To override channels, include the channels array in event property and add the corresponding key in the override channels field on SuprSend workflow form. The expected channel value in the array is:

However, channel is added as a JQ-expression in workflow form. So, in case your channel values do not match with the one mentioned in the above table, you can transform it using the JQ-expression.

For example if this is the event call

distinct_id = "0fxxx8f74-xxxx-41c5-8752-xxxcb6911fb08" # Unique id of user in your application

event_name = "product_purchased"   # name of the event you're tracking

# Properties: a dict representing event-attributes
properties = {													
  "first_name": "User",
  "spend_amount": "$10",
  "channels":["email","sms","slack"]
}

event = Event(distinct_id=distinct_id, event_name=event_name, properties=properties)

You can add .channels key in workflow form on SuprSend dashboard to override channels with the channels array in event property.

Below are some examples of how to enter channels in the workflow using JQ-expression:

1. If the channels is a nested event property key like shown below, enter in the format .user.channels.

properties = {													
  "user": {
    "name": "Steve",
    "channels": ["email","inbox]
  }
}

8. Notification Category

Notification category is either System, Transactional, Promotional. You can understand more about them in the 'Notification Category' section.

9. Success Metric

Success metric will be used to measure the success of your workflow. It has three options:

• Seen: If notification on any of the channels is seen by user, consider it a success.
• Interaction: If notification on any of the channels is clicked/interacted by the user, consider it a success.
• Custom event: Custom event will be any user-defined event passed to SuprSend Platform. You'll have to provide 'Event name' if you set success metric type as 'Custom Event'.
  • Here, success will be considered if custom event is done by user within the event-window (1 day)
  • Currently, event-window is not configurable. default set to 1d (1 day). Any event which is done after the event-window is over will not be considered as a success

Default value: Seen

10. Delivery Preference

Delivery preference has two options:

• Send to All Channels at once: Workflow delivers communication to a user on all the channels available at the same time
• Smart Delivery: Workflow delivers communication to a user in a sequential manner in the order of Notification cost (low to high), starting with the channel with the lowest Price per notification. The communication will be sent on channels until the success metric is achieved. Sending in sequential manner has following advantages:
  • Your end user is not bombarded with the same communication on all the channels.
  • You save cost of channels by avoiding redundant channels once the success metric is achieved.
    
    

Smart Delivery Settings

Multi-channel strategy is indeed important to increase the effectiveness of communications (eg. it improves overall delivery rate, seen rate and interactions), but it comes with a side effect. While the intention is right to reach out to your users on multiple channels, it sometimes leads to user bombarding. Example, you have created templates for 4 channels, when a notification is triggered, it goes to all the channels together. For a user who has already seen the message or interacted with the message on 1 channel, rest of the channels are just noise. Needless to say, it is also a cost to the company.

SuprSend Workflows handle this via Smart Delivery. Delivery options associated with Smart Delivery are:

1. Time to live (TTL):

Time-window for which your workflow is relevant. Notification on each channel will be sent with time-interval of [time_to_live / (number_of_channels - 1)] apart. (Eg. if there are 3 channels active for a workflow and time to live is set to 1 hour. Notification on one channel will be sent immediately and other 2 channels will be notified at every 30 mins (1 hour / 2) gap)

By default, TTL will be set to '1 hour'

2. Mandatory Channels (Optional):

Channels on which notification has to be sent immediately (irrespective of notification-cost). Multiple channels can be set as mandatory channels.
It is an optional field and by default, there'll be no mandatory channels selected

How Smart Delivery Works?

• When you turn on Smart Delivery, Workflows pick up mandatory channels provided and triggers notification on them immediately. If there are no mandatory channels provided, workflows order channels in low-to-high cost basis, and trigger notification on first channel in the order immediately. Cost is picked up from the value entered in Vendor Settings page. Eg. FCM has 0 cost and it will be picked up first. If cost is not mentioned, it is considered 'zero' for order-calculation purpose.
• Now for rest of the channels, workflows will trigger on them one by one with some interval between them. This time interval is calculated from time_to_live you have defined: time-interval = [time_to_live / (number_of_channels - 1)]. Eg. if you provide 4 channels and your message is relevant for 1 hour (ie. time_to_live = 1 hour), first channel will be triggered immediately, and the rest 3 will be triggered in every 20 minutes.
• In between the channel triggers, workflows will listen to the response, and check whether the success defined is met or not. If it is met, rest of the channel triggers are not attempted. If success is not met, the process will continue until all channels are exhausted.

How to Check Active Workflows on SuprSend platform?

On the SuprSend platform, you can check all the Active / Inactive workflows from 'Workflows' tab.

1. You can go to the tab by clicking on 'Workflows' in the left Navigation Panel.

2. The list shows all the Workflows, along with the templates used, notification category, status, updated by, and last updated on.

3. All the workflows with the 'updated by' value = "Dynamic Workflow" are the workflows that are created from Backend. You cannot edit these workflows on SuprSend platform. You cannot mark these workflows as 'Inactive' from the SuprSend platform either.