Skip to main content

Getting Started with Event Delivery

PhotonIQ Event Delivery is a fully managed service, implemented and optimized by Macrometa engineers to ensure proper functionality. For those who prefer a more hands-on approach, this guide provides information to help you actively manage the EDS.

In this guide, you'll learn how to:

The Event Delivery service enables you to stream and filter events from Macrometa streams, as well as publish events to these streams. Before you proceed, here are some key concepts:

  • Publisher: In the Event Delivery Service (EDS), the publish API enables applications to send events to streams (GDN collection streams and GDN streams).
  • Subscriber: An entity that subscribes to events from the publisher. Subscribers can use SQL-like queries to filter and subscribe to specific events, reducing noise and focusing on relevant data.
  • Stream: A named channel for sending messages. Every stream in the GDN is backed by a distributed append-only log and can be either local (restricted to one edge location) or global (spanning all edge locations in the fabric).
  • Event: Each new data point or message generated by the publisher.

Setup event stream in the PhotonIQ GDN​

Setting up your event stream in the GDN for EDS involves two phases: GDN account setup and EDS server configuration.

GDN account setup​

Prerequisites

  • A Macrometa account with sufficient permissions to create collections. You can contact a Macrometa partner to sign up or sign up on your own. Once your Macrometa account is set up, you can choose the type of collection to stream your data into. The PhotonIQ GDN offers the following options for EDS:
tip

Consult your Macrometa partner to help decide the best type for your business use case.

Now, proceed to set up your collection stream in the GDN following these steps:

  1. Create a Fabric for your collection to specify where your data resides. If you skip this step, the collection will be placed in the system fabric.
  2. Create a Collection to receive streaming data. For this guide, we'll be using Document Collection.

New Collection Stream

tip

Ensure you enable Collection streams and select a Distribution when creating the collection.

  1. Now that you've succesfully created a collection, add some data to that collection. Adding data to the collection depends on the type of collection you created.

    • Navigate to the collection you created and click New Document
    • Enter a key or leave empty for an auto-generated key.
    • To add data to this document, toggle the Tree option to Code and add the following JSON:
    {
      "first_name": "Jenny",
      "service": "Executive",
      "attendance":4
    }
    • Click Save
    • You can create multiple documents if you choose. Each of them will have a unique key. You can also navigate to Settings to view more details about the collection.

EDS server configuration​

Contact Macrometa with your GDN details to set up your EDS server. Before proceeding to the next step, ensure you receive the required access information for the EDS server, including the EDS host, API key, and customer ID.

Subscribe to events and recieve real time updates​

Once you've set up your event collection stream, you can subscribe to the Event Delivery Service (EDS) to receive live updates using the Event Delivery API.

Subscribing to the EDS​

The subscribe to stream API requires the following fields:

  • EDS host: The host where the EDS service is running.
  • Customer ID: This is used to identify the user making the request.
  • Filters: Use filters to control the behaviour of your events and define the SQL queries to be executed. Refer to Event Delivery Filters to learn more.
  • API key: This is used to authenticate the request.
info

Contact Macrometa for your EDS host, API key, and Customer ID.

In this sample guide, you'll be subscribing to the stream and fetching all the document in the collection where attendance=4.

The endpoint URL for subscribing to the stream via WebSocket follows this format:

wss://<eds-host>/api/es/v1/subscribe
info

Curl currently has no support for WebSockets, so we'll make this request using wscat.

To susbscribe to the stream via WebSocket, use this command:

wscat -c 'wss://<eds-host>/api/es/v1/subscribe?apikey=<api_key>&type=collection&x-customer-id=<x-customer-id>&filters={"action": "add", "once": "FALSE", "initialData":"TRUE", "queries": ["select * from <collection-name> where attendance=4"]}' | sed -r "s/\x1B\[([0-9]{1,2}(;[0-9]{1,2})?)?[mGK]//g"

Replace the following:

  • <eds-host> with your actual EDS host address.
  • <x-customer-id> with your customer ID.
  • <collection-name> with the name of the collection you created earlier.
  • <api_key> with your API authentication key.

On sucessful subscription, the Websocket connection is created and the following information is included in the first response alongside the selected data from the collection:

  • x-photoniq-es: Epoch time header. This is the Unix timestamp in seconds since epoch. It provides the epoch time in seconds.
  • x-photoniq-customerid: Customer ID header. It is the customer identifier header.
note

The sed regex filter at the end removes any terminal color codes and control characters, it can be ignored.

Now that you've succesfully subscribed to the stream, the connection actively listens for any change made to the data.

Receive real-time updates from subscribed streams​

While the SSE or Websocket connection is open, all event updates for the subscribed collection are returned through the connection.

  1. Go to the Collection and select any document data where attendance=4.
  2. Toggle the Tree option to Code and change the first_name to Mark:
{
  "attendance": 4,
  "first_name": "Mark",
  "service": "Executive"
}

The connection in the terminal immediately returns fresh data with the updated value of Mark as first_name.

Publish Events to Data Stream​

Unlike subscribing that occurs through a Websocket/SSE connection, publishing an event through the EDS occurs via HTTPS. A sample publish event API call looks like this:

curl -X POST 'x/api/es/v1/fabric/<fabricName>/stream/<streamName>/publish?type=collection' -d '{"foo": "bar"}' -H x-customer-id=cust-edsgdn

Monitor the Event Delivery metrics and health status​

To monitor and evaluate the health status of the EDS, use the Event Delivery Metrics and Health API.