StediDOCS
GuidesAPI Reference
This product is in Developer Preview

Events

Getting Started

Events is a Stedi product enabling customers to subscribe and automatically react to business events as they happen – either from custom events generated by external systems or from a wide array of Stedi products. Events generated by Stedi products are typically triggered by state changes, such as a new document being created in the Document Store. Customers can create event subscriptions with HTTP event targets, which are called in response to these events occurring.

Using Events and Event Subscriptions

In order to listen to an event or connect another Stedi product to a certain type of an event, you need to create an Event Subscription.

Event Subscriptions can be created, updated and tested within the Terminal.

Creating an Event Subscription

To create an event subscription, click on the Events tab in the navigation menu. Then, click on the Create Event Subscription button located in the top right corner of the page.

Currently only supported via API

Currently, only via the API, you can also define event details, an object containing key value pairs, where the key is the event detail property on which you want to filter on, and the value an array of filters for its specific content.

Note. If you've chosen a Stedi Workflow, be careful which workflow you choose, as it will be invoked on every incoming event.

Enabling and Disabling Event Subscriptions

Every Event Subscription can be manually enabled/disabled from:

  • the Event Subscriptions Table, at the end of each row you will see a switch to enable / disable the event subscription.
  • the Event Subscriptions Detail page, when you open a specific Event Subscription, you can see the Enabled / Disabled button on top right.
  • when editing or updating your Event subscription, you can see the Enabled / Disabled button on top right, as well.

Content Filtering

Currently, supported only via the Events API. Stedi Terminal and Formation support coming by September 15th 2021.

Stedi Events supports declarative filtering on event content, as well as filtering on event source and type. Simply, when creating an Event Subscription provide an array of filters for the event source, type or for each detail property you want to filter on.

Supported filter types

Event Subscriptions support two types of filters, for numeric and string values.

String filters

String filtersDescription
starts_withIncludes events with that property's value starting with a specific value, identical to a prefix filter.
includesListents to events with a property's value that contains that specific value
excludesRepresents an anything-but filter, which ignores events that contain that specific value.
ends_withIncludes events with that property's value ending with a specific value, identical to a suffix filter.
exact value filteringSupported by simply providing that value in the array of filters.

Numeric filters

Numeric filtersDescription
greater_thanInclude all values above a certain threshold.
less_thanInclude all values below a certain threshold
exact value filteringSupported by simply providing that value in the array of filters.

Note. Additionally, you can combine those filters all together with the field filter array.

Nested filtering

Currently isn't supported, the Event Subscription filters only go to one level, but this is on the Events roadmap, and will most likely be done by the end of Q3 2021.

Example Event Subscription with Filters

An example Event Subscription for a Document Store Event with some of the filters on each supported field follows:

{
  name: "Example event subscription",
  filter: {
    source: [{ starts_with: "com", ends_with: "docstore" }, "com.stedi.docstore"],
    type: [{ starts_with: "document", excludes: "deleted" }, "document created"],
    detail: {
      name: [
        { starts_with: "document_name", includes: "unprocessed", ends_with: "2021.pdf" }, "document_name_unprocessed_2021.pdf",
      ],
      size: [{ greater_than: 1024, less_than: 2048 }],
    },
  },
  target: {
    config: {
      method: "POST",
      url: "https://localhost.com/some-url",
    },
    type: "webhook",
  },
}

The code example demonstrates a few of the string filters supported with event subscription filtering. Specifically, it shows an event subscription with filters that are listening specifically for all but document deletion Stedi Document Store events concerning documents "unprocessed 2021.pdf" in ther name.

Formation Template

The same example Event Subscription can be defined as a Stedi::EventSubscription Formation Resource type using the following code:

{
  "Resources": {
    "MyEvent": {
      "Type": "EventSubscription",
      "Properties": {
        "Name": "Example event subscription",
        "Filter": {
          "Source": [
            {
              "starts_with": "com",
              "ends_with": "docstore"
            },
            "com.stedi.docstore"
          ],
          "Type": [
            {
              "starts_with": "document",
              "excludes": "deleted"
            },
            "document created"
          ],
          "Detail": {
            "Name": [
              {
                "starts_with": "document_name",
                "includes": "unprocessed",
                "ends_with": "2021.pdf"
              },
              "document_name_unprocessed_2021.pdf"
            ],
            "size": [
              {
                "greater_than": 1024,
                "less_than": 2048
              }
            ]
          }
        },
        "Target": {
          "Type": "webhook",
          "Config": {
            "Url": "https://localhost.com/some-url",
            "Method": "post"
          }
        },
        "Enabled": true
      }
    }
  }
}

API Reference

Getting StartedUsing Events and Event SubscriptionsCreating an Event SubscriptionCurrently only supported via APIEnabling and Disabling Event SubscriptionsContent FilteringSupported filter typesString filtersNumeric filtersNested filteringExample Event Subscription with FiltersFormation Template