[Recipe] External events

[slashdotdash]

How to capture external events, such as those recorded by an IoT device.

Events can be directly appended to an event stream, using Commanded.EventStore, without needing to be produced by an aggregate from a command. An event handler can be used to react to these external events. It may dispatch a command as a reaction to an event.

1. Define an integration event struct which can be used for any external event without needing to define a custom struct for each type.

   defmodule MyApp.Integration.Event do
     defstruct [:source, :type, :data]
   end

   The type of the external event will be indicated by the type field. This allow loose coupling which is preferred when dealing with events from a third party, external system.

2. Append events to a stream (e.g. devices/device-1234) using Commanded.EventStore.append_to_stream/4 and an integration Commanded Application instance.

   source = "devices/device-1234"
   
   events = [
     %Commanded.EventStore.EventData{
       event_type: "Elixir.MyApp.Integration.Event",
       data: %MyApp.Integration.Event{
         source: source,
         type: "ThirdPartyService.SomeExternalEvent"
         data: %{
           "key1" => "value1",
           "key2" => "value2"
         }      
       },
       metadata: %{}
     }
   ]
   
   :ok = Commanded.EventStore.append_to_stream(MyApp.Integration.App, source, :any_version, events)

   As these are external events we are storing in raw format we can use :any_version to skip concurrency control checking.