External services
Chronicle.ExternalServices provides an idiomatic Elixir API for registering external service definitions with Chronicle.
External services let the Chronicle kernel talk to systems outside the event store — an HTTP API or a MsSql/PostgreSql database — under a name other kernel features (such as captures) can reference. They are usually configured in the Workbench, but the Elixir client also exposes a programmatic API.
Definitions are registered against the selected client’s event store, not a namespace. Choose an HTTP or database definition and confirm the endpoint and authority before registration. Keep credentials and connection details out of shared diagnostics.
Registering an HTTP service
Section titled “Registering an HTTP service”Register an HTTP endpoint with bearer-token authentication and a custom header:
:ok = Chronicle.ExternalServices.register("CustomersApi", fn builder -> builder |> Chronicle.ExternalServices.DefinitionBuilder.http("https://api.example.com") |> Chronicle.ExternalServices.DefinitionBuilder.with_bearer_token(token) |> Chronicle.ExternalServices.DefinitionBuilder.with_header("X-Tenant", "acme") end)configure receives a Chronicle.ExternalServices.DefinitionBuilder and must return it (or a continuation of it) once the endpoint is configured.
Registering a database service
Section titled “Registering a database service”Register a PostgreSQL database endpoint:
:ok = Chronicle.ExternalServices.register("CustomersDb", fn builder -> Chronicle.ExternalServices.DefinitionBuilder.postgre_sql( builder, "db.example.com", "customers", "postgres", password, 5432 ) end)Use Chronicle.ExternalServices.DefinitionBuilder.ms_sql/6 instead for a Microsoft SQL Server endpoint — it takes the same host, database, username, password, and port arguments.
Builder API
Section titled “Builder API”Chronicle.ExternalServices.DefinitionBuilder is immutable and pipeline-friendly.
The scope argument of with_oauth/5 is optional. Omit it and no scope is requested from the authority. It applies to the outbound OAuth client-credentials call only, not to the client’s own connection to the kernel.
http/2configures an HTTP endpoint.ms_sql/6andpostgre_sql/6configure a database endpoint — mutually exclusive withhttp/2and each other; the last call wins.with_basic_auth/3,with_bearer_token/2, andwith_oauth/4(orwith_oauth/5with an optional scope) are mutually exclusive with each other and only meaningful for HTTP endpoints.with_header/3adds or replaces an HTTP header sent with every request.with_option/3adds a provider-specific option to a database endpoint’s connection configuration.
The authentication setters in this catalog are alternatives, not a cumulative pipeline to run. Choose basic, bearer or OAuth; a later authentication setter replaces the earlier choice.
builder|> DefinitionBuilder.http("https://api.example.com")|> DefinitionBuilder.with_basic_auth("user", "password")|> DefinitionBuilder.with_bearer_token("token")|> DefinitionBuilder.with_oauth("https://login.example.com", "client-id", "client-secret", "api.read")|> DefinitionBuilder.with_header("x-tenant", "acme")Using a named client
Section titled “Using a named client”:ok = Chronicle.ExternalServices.register( "CustomersApi", fn builder -> Chronicle.ExternalServices.DefinitionBuilder.http(builder, "https://api.example.com") end, client: :bank_chronicle )