Introduction

On this page, you will learn how to define a Zeleo Application including the Events and Conseqeuences that will interact with Zeleo. After setting up and defining the Application, the pages that follow explain how to create the service that interacts with the Zeleo platform.

Proper Permissions

The first thing you will need to do is make sure you have Development permissions inside Zeleo. Open your User Menu and make sure Manage Team is available. If not, you can either ask the owner of the team to give you Admin permissions for this team, or create a new team using the Create Team button. If you create a new team, you will automatically be an Administrator of that team.

User Menu

Now, open the Manage Team dialog and ensure that the wrench icon to the right of your name is green. You should see a tab on your Dashboard named Development. Once that is there, we’re ready to begin!

Starting Your First Application

When you first open the Development tab, a new Zeleo Application will be set up automatically, though it will not exist until it is saved.

Development Tab

The first section is pretty straightforward; you can add an icon for the Application, as well as a name, author, and summary. These can be changed at any time, so don’t worry if it’s not perfect. Hit the Save button to save all of your information at any time.

Remember, your Zeleo Application will only be available to your team unless you submit for publishing, so feel free to experiment.

The Description field is an HTML formatted explanation of the events and any setup required by the user. The eye icon above shows a preview of the description using the same control shown to the user in the Zeleo client. We recommend at least having the following sections covered:

  • Overview
    • A brief summary of the service and what it can do for the user.
  • Events
    • A list of the events available.
  • Consequences
    • A list of any consequences the service can offer.
  • Setup
    • Any setup instructions required to get the service up and running.

Security

The Security section defines the authentication of the REST calls between the Zeleo servers and your service. We employ the JWT technology to ensure only the service owner (you) is able to fire events for your service and likewise for any webhook consequences. We will get to this when we start implementing the service, but basically the four fields are ingredients when you generate a JWT token; all four must match exactly what is here. Be sure not to show them to anyone, especially the Token field which is generated and assigned by our server when you save for the first time.

Events

In this section, you define the events that can be fired for the Zeleo engine to process. What you are doing here is providing the interface for the JSON object that gets sent in from your service.

Here’s a sample of the GitHub Application developed by Zeleo:

Events Section

The first thing your will do is hit the + icon to add a new event and give it a name. For each event, there will be variety of fields, each with the following:

  • Name
    • This is the name of the field that is displayed to the user in the logic editor.
    • Make sure this is in plain English, and feel free to use spaces.
  • Key
    • This is the key in the JSON document that gets passed to Zeleo.
    • Since it’s JSON, be sure not to use spaces or any other characters that are invalid.
  • Type
    • The type of the field. If you specify an array type such as MultipleChoice, you will be able to add your options under the field.
    • The Person type is special. This means the field defines a person; we will get to how this works in another section. In this GitHub example, you will use this field to send over the GitHub username since it defines the person who is the subject of the event.

When the user enables your Zeleo Application, the events will show up in the Rule Builder as follows:

Rule Builder

Once you have an event added to your Zeleo Application, go ahead and add it to your team and see the events show up in your Rule Builder! You can enable your Zeleo Application by hitting the + icon next to it in your Manage Team dialog’s Applications tab.

Add Applications

Consequences

Conseqences are webhooks to your service that can be fired if the Condition is true, regardless of the event that triggers it. Bear in mind that this might not always be one of your defined events that causes this to fire; it could be any event from any other system, or Zeleo itself.

Consequence Definition

You define a consequence by hitting the + icon in the Consequences section. You will then need to fill in:

  • Application URL
    • This is the root host/port/path that all your webhooks have as a base.
  • Consequence Name
    • The name that will be displayed to the user in the UI.
    • Again, since this is just for display, feel free to use spaces, etc.
  • Consequence WebHook
    • The path to your webhook. This will be added to the Application URL when it is fired.
    • All webhooks are REST POSTs that contain a JSON object. We will get into that in more detail when we create a Consequence service.
  • Consequence Fields
    • For every consequence, you can add fields that the user can configure as well.
    • This is in addition to the event JSON object which will be sent to your service as the payload of the WebHook.
    • Just like the event fields, you add a name, key, and type.
    • If you set the type as Template, the user will be able to select a Communication Template to send to the webhook. The fields of this template wil be replaced prior to sending; this is very useful when integrating with communication systems like Slack.

Once saved, the consequence will be available in the Rule Builder. You may need to close and reopen the Workspace to load the changes.

Consequence Rule Builder

Team and User Options

This section allows you to define any configuration options required for the Zeleo Application, both at the the team and user level. Options under the Team Option will be available for the Team Administrator to configure only for the whole team where everyone will see any User Options in their Edit Profile dialog.

Configuration Options

Fields are defined as follows:

  • Configuration
    • This is the name that will be shown to the user inside Zeleo.
    • Just as before, use spaces as needed; this is just for the UI.
  • Field Type
    • You can set the type of the field here.
    • There are two important types besides the normal String, Integer, etc.
      • Person
        • This means this field will identify a person in Zeleo. Most systems have some sort of identifier, be it an account name, id string, or email address.
        • The user will add this to their account this way.
        • If an event has a field of type Person, and the json key of that event is listed as a reference to this field, Zeleo will automatically match the event to the user.
        • For instance, in GitHub, the field is a person’s GitHub Username. An event might have an ‘assignee’ field that contains that Username. Zeleo knows that the GitHub event is talking about the user whose GitHub Username configuration matches that assignee string.
      • Filter
        • Only available at the team level, this works similarly to the Person type.
        • You can specify a field that must match this filter, or else other fields are ignored.
        • An example of this is te GitHub ‘Repository’ filter where you ca specify a repository string.
          • All events from GitHub that come from a different repository will be ignored by this team.
  • Reference
    • This field only shows up for Person and Filter types as you have to specify the JSON Key of the event which contains the field that will be talking about this option.
    • For instance, if you have a Person field in an event with a username, and you set a Person type option, you need to tell Zeleo that a give event field should be linked with this option value.
  • Description
    • A brief description for the UI.
  • Required
    • Whether the field is required.

Fields will show up in the UI. For instance, User Options show up as follows in the Profile dialog.

User Configuration

Team Options show up the the Manage Team dialog using the gear icon:

Team Configuration

Options that are not Person or Filter can be retrieved by your service through REST endpoint. We will get to that later when writing the service.

Summary

Now you have the Zeleo Application defined in Zeleo. The events and consequences that Zeleo expects are now available in the Rule Builder, you have your security information ready, and any options that you need will be available to either your service or to automatically apply. In the next documents we will dive into the service itself!