Skip to content

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.

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.

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.

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/2 configures an HTTP endpoint.
  • ms_sql/6 and postgre_sql/6 configure a database endpoint — mutually exclusive with http/2 and each other; the last call wins.
  • with_basic_auth/3, with_bearer_token/2, and with_oauth/4 (or with_oauth/5 with an optional scope) are mutually exclusive with each other and only meaningful for HTTP endpoints.
  • with_header/3 adds or replaces an HTTP header sent with every request.
  • with_option/3 adds 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")
:ok =
Chronicle.ExternalServices.register(
"CustomersApi",
fn builder -> Chronicle.ExternalServices.DefinitionBuilder.http(builder, "https://api.example.com") end,
client: :bank_chronicle
)