Skip to content
Yetto Docs

Creating switches

Switches are the foundation of information flow and activity in Yetto. You can create switches in your inboxes to add custom automations, such as applying labels and sending data to your webhooks.

You can even create switches which schedule actions in the future. This can be especially useful for teams looking to implement SLA policies.

The anatomy of a switch

Yetto's switches are written in JSON have a couple of standard keys. Let's look at one and break it down as an example.

{
  "version": "2023-03-06",
  "events": {
    "message.created": {
      "conditions": {
        "if": "{% data.yetto.message.visibility == \"internal\" and data.yetto.message.text_content contains \"@label add urgent\" %}"
      }
      "actions": [
        {
          "uses": "apply_labels",
          "add": [
            "bug.urgent"
          ]
        }
      ],
    }
  }
}

Let's look at each of these configuration keys one by one.

Version

This is a required field and should typically be set to the newest switch version. As of writing this, the latest switch version is 2023-03-06. Using a different version could create unexpected behaviors.

Events

The events object is required. This tells Yetto what events to act on and what to do when the event occurs. Each switch can contain multiple events to watch for. In this example, we're going to act on the message.created event.

A list of available events that Yetto listens for can be found in our switch reference document.

Conditions

Here we can tailor the switch action to be more specific. Yetto allows if and unless objects as conditions, both of which use Liquid as their templating language. You have access to the full object that triggered the switch event when writing these, namespaced as data.yetto.*. Let's look at our example again.

"conditions": {
  "if": "{% data.yetto.message.visibility == 'internal' and data.yetto.message.text_content contains \"@label add urgent\" %}"
}

Here we use want only internal messages containing specific text. Note that the text content is escaped using \s in Liquid.

All of the available object properties will be enumerated in our reference docs.

Actions

The actions array is where you'll tell Yetto what you want to do when the specific event triggers the switch. This is a required object and will always include a uses string.

Each action behaves a little differently and may require other object properties to work. The actions and their requirements are described in "Available switch actions."

Scheduling

You can also schedule switch actions to occur in the future. Scheduling actions respond to events, but make use of an entirely different keyword, scheduled:

{
  "version": "2023-03-06",
  "events": {
    "message.created": {
      "scheduled": [
        {
          "after": "8 hours",
          "actions": [
            {
              "name": "Set respond-now label",
              "uses": "apply_labels",
              "add": [
                "sla.respond-now"
              ]
            }
          ]
        }
      ]
    }
  }
}

scheduled is an array of objects, which have required after and actions keys, and an optional conditions key. actions and conditions are the exact same format as described above. after determines when your action will fire. It should be defined in the form of a number, followed by either a shortcode for time or the time unit spelled out. The shortcodes include:

  • m for minutes
  • h for hours
  • w for week

You cannot set the after time to a moment that is less than 30 minutes away, or greater than one week.

For example, the following are valid:

  • "after": "30m": 30 minutes
  • "after": "30 minutes": 30 minutes
  • "after": "2h30m": two hours and 30 minutes
  • "after": "2 hours and 30 minutes": two hours and 30 minutes
  • "after": "1w": one week

The following are not valid:

  • "after": "5m"
  • "after": "two hours"
  • "after": "2 hrs"
  • "after": "2w"

Note that conditions are evaluated at the time the action runs. As a demonstration, in the example below, if the conversation is closed between the first and second action, the second action does not fire, because its conditions are evaluated to false:

{
  "message.created": {
    "scheduled": [
      {
        "after": "2 hours",
        "conditions": {
          "if": "{% data.yetto.message.conversation.state == \"open\" %}"
        },
        "actions": [
          {
            "name": "First action",
            "uses": "apply_labels",
            "add": [
              "sla.respond-now"
            ]
          }
        ]
      },
      {
        "after": "4 hours",
        "conditions": {
          "if": "{% data.yetto.message.conversation.state == \"open\" %}"
        },
        "actions": [
          {
            "name": "Second action",
            "uses": "apply_labels",
            "add": [
              "sla.urgent"
            ]
          }
        ]
      }
    ]
  }
}

Make your own

To create your custom switch:

  1. Go to the "Switches" section of your inbox settings.
  2. Click "Add new switch".
  3. Enter a unique name for your switch in the "Name" field. This should be descriptive enough for you to know what it's doing at a glance. "VIP automations" or "Urgent labels" are good examples.
  4. Write the switch as valid JSON in the text field. You can start by copying and pasting an existing switch and then modifying the events and actions to suit your needs.
  5. Click "Create switch".

Your switch is now installed on your inbox and ready to use.

See some examples

Yetto uses switches under the hood to send data between plugs. Once you have a plug installed on your inbox, you can view the switches it uses to operate. Go to the "Switches" section of your inbox settings and click "View" on any of the switches listed there. That will give you an idea of how we use them internally to automate activity within Yetto.