Cratis Chronicle captures: turn changes into events
Cratis Chronicle captures turn changes in external data into events in your event store. Use a capture to detect changes in API data or translate another event store’s public events into your own private events, without writing that detection or translation loop yourself.
HTTP source destinations
Section titled “HTTP source destinations”API polling uses the Kernel’s independent ExternalServices destination policy. Development builds
warn by default; other builds block local destinations unless their host is explicitly approved.
Redirects and proxies are disabled, and both relative and absolute capture routes are checked with
the capture’s event-store context. Webhook approvals do not apply. See
HTTP capture destination policy
for modes, private-network approvals, metadata protection, configuration, and upgrade guidance.
Overview
Section titled “Overview”For API data, a capture polls a configured service and compares each observation with the previous one. An identity key, such as an invoice ID, tells Chronicle which items to compare. Append rules select the event to emit when an item is added, removed, or changed, and field assignments build its payload. This is change data capture (CDC): the events describe changes in the source data rather than commands sent to your application.
An events capture reads public events delivered through an inbox, the event sequence that receives events from another event store. It merges their payloads into state for each key, then applies append rules to produce local private events. Use this when your event store needs its own interpretation of another store’s public contract.
Capture Declaration Language (CDL) is the language-neutral text format parsed by the kernel. If you prefer definitions alongside application code, .NET offers a declarative API with fluent C# builders and a model-bound API with attributes. The Elixir capture DSL compiles module definitions to CDL. Choose the authoring page under Topics for the approach you want to use.
Define and manage a capture in your client
Section titled “Define and manage a capture in your client”In Elixir, define a module with use Chronicle.Captures.Capture to keep the source, identity key, and append rules together. The DSL compiles to CDL at build time.
defmodule MyApp.Events.CapturesIndexInvoiceStatusChanged do use Chronicle.Events.EventType, id: "InvoiceStatusChanged"
defstruct [:status]end
defmodule MyApp.Captures.CapturesIndexInvoiceCapture do use Chronicle.Captures.Capture, name: "InvoiceCapture"
alias MyApp.Events.CapturesIndexInvoiceStatusChanged
api_source("InvoicingApi", route: "/invoices", poll: "10m")
key("id")
append CapturesIndexInvoiceStatusChanged, when: "status" do set(:status, "$.status") endendThe DSL also lets you express mapping, nested, and children constructs. The following snippet shows that authoring syntax, not an executable capture: the engine rejects those constructs during validation.
defmodule MyApp.Events.CapturesIndexCustomerChanged do use Chronicle.Events.EventType, id: "CustomerChanged"
defstruct [:first_name, :last_name]end
defmodule MyApp.Events.CapturesIndexBillingAddressChanged do use Chronicle.Events.EventType, id: "BillingAddressChanged"
defstruct [:street]end
defmodule MyApp.Events.CapturesIndexItemAdded do use Chronicle.Events.EventType, id: "ItemAdded"
defstruct [:line_number]end
defmodule MyApp.Captures.CapturesIndexCustomerCapture do use Chronicle.Captures.Capture, name: "CustomerCapture"
alias MyApp.Events.{ CapturesIndexBillingAddressChanged, CapturesIndexCustomerChanged, CapturesIndexItemAdded }
api_source("CustomersApi", poll: "5m")
key("customerId")
map do rename(:full_name, :fornavn) translate(:status, :status, [{"aktiv", "active"}, {"inaktiv", "inactive"}]) end
append CapturesIndexCustomerChanged, when: {:any, ["firstName", "lastName"]} do set(:first_name, "$.firstName") end
nested :billing_address do map do rename(:street, :"fakturaAdresse.gate") end
append CapturesIndexBillingAddressChanged, when: "street" do set(:street, "$.street") end end
children :line_items, identified_by: :line_number do append CapturesIndexItemAdded, when: :added do set(:line_number, "$.lineNumber") end endendUse the client to validate a declaration, register and start a capture, or inspect recently captured events. You can also list, stop, and delete captures:
defmodule MyApp.CapturesIndexManage do alias MyApp.Captures.CapturesIndexInvoiceCapture
def register_and_start do {:ok, _capture} = Chronicle.Captures.register(CapturesIndexInvoiceCapture) :ok = Chronicle.Captures.start(CapturesIndexInvoiceCapture) end
def list_captures do Chronicle.Captures.list() end
def validate_declaration do Chronicle.Captures.validate(CapturesIndexInvoiceCapture) end
def recent_captured_events do Chronicle.Captures.captured_events("InvoiceCapture", max_events: 50) end
def stop_and_delete do :ok = Chronicle.Captures.stop(CapturesIndexInvoiceCapture) :ok = Chronicle.Captures.delete(CapturesIndexInvoiceCapture) endendTopics
Section titled “Topics”Start with CDL to write a text definition or look up syntax. Choose a client-specific page to define the capture in application code.
| Topic | Description |
|---|---|
| Capture Declaration Language | CDL syntax, semantics, and formal language specification |
| Declarative Captures | .NET client fluent API (ICapturer + ICaptureBuilder) |
| Model-Bound Captures | .NET client attribute-based capture declarations |