Skip to main content

Configuration

This page provides guidance on configuring actors that participate in a Concordance application through the capability provider. Note that this configuration mechanism is potentially subject to change as the developer experience improves. There are plans in the roadmap to support a more holistic or unified configuration by way of defining an event sourced application as a graph (e.g. RDF, etc). But for now, applications are configured by having each actor supply configuration on a per link definition basis.

Aggregates​

An aggregate must supply four fields in the link definition:

  • ROLE - this must be set to aggregate and nothing else
  • NAME - the name of this entity. This name will be used in naming and describing NATS consumers, etc. Will be converted to snake case if you don't supply it that way, e.g. bankaccount or bank_account.
  • INTEREST - this is the name of the stream on which the aggregate sits. A common convention is for this to be the same as the entity name.
  • KEY - This is the field within the payload that uniquely identifies a single instance of the aggregate. For example, this might be account_number for a bank account aggregate.

Projectors​

A projector must supply the following fields in the link definition:

  • ROLE - this must be set to projector and nothing else
  • NAME - the name of the projector. This name is used for naming and labeling various low-level components. This should be pure alphanumeric with no special characters
  • INTEREST - This is a comma-separated list of event types that this projector listens to

Process Managers​

A process manager supplies a slightly more complex configuration because it declares a specification for its lifetime. This specification is what Concordance uses in creating, updating, and deleting per-process state. The following is a list of fields that must be on every process manager link definition:

  • ROLE - this must be process_manager and nothing else
  • NAME - the name of the process manager. This must be pure alphanumeric.
  • INTEREST - this is a JSON payload containing the lifetime specification (shown below)
  • KEY - the key field for the process manager. This uniquely identifies one instance of a process. Note that it is commonplace for aggregates and process managers to have entirely different key fields.

Lifetime Specification:

{
  "start": "account_created",
  "advance": ["funds_withdrawn", "funds_deposited"],
  "stop": ["account_closed"]
}

The event types here must match exactly the event types on the events emitted by other primitives. This will get much easier and potentially automatic once more code generation and tooling is added to support Concordance.

Notifiers​

A notifier is just a primitive that accepts events and emits nothing in response. It must still declare which events it is interested in so the capability provider can properly manage it.

  • ROLE - this must always be notifier
  • NAME - the entity name for this notifier
  • INTEREST - a comma-delimited list of events in which this notifier is interested

Capability Provider Base Configuration​

If you want to override the default configuration for this provider, then you can supply start configuration via the wash command when you start the provider. The startup configuration is a JSON payload that looks as follows:

{
  "nats_url": "nats://0.0.0.0:4222",
  "user_jwt": "xxx",
  "user_seed": "xxx",
  "js_domain": "xxx"
}

By default, the provider connects anonymously to the local NATS server. If you want to change this you'll need to change the base configuration. If you supply a user_jwt you must also supply a user_seed value. The js_domain value is optional and only needed if you are doing things like attempting to reach streams from across a NATS leaf node boundary.