eleconf

Eleconf

Tool for applying configuration to changes to the Elephant repository.

Enforces configuration for:

* Schema versions
* Meta type configuration
* Document statuses
* Document workflows
* Document type configuration (bounded collections, time/label expressions, eviction)
* Metric kinds

Configuration

Eleconf uses HCL as its configuration language.

See example configuration files in the examples/tt folder.

Schema sets

An organisations schemas are often split into several files for readability, but versioned together. Therefore schemas are configured as schema sets.

Schemas can either be loaded from a git repository, or over http(s).

Example schema set block:

schema_set "core" {
  version      = "v1.0.5-pre1"
  repository   = "https://github.com/ttab/revisorschemas.git"

  schemas = [
    "core",
    "core-planning",
    "core-metadoc",
  ]
}

As we specify a repository here the version must be a valid git tag. And the schemas files themselves are assumed to be located in the root of the repository.

If the schemas are to be loaded over http we can instead provide an URL template like so:

url_template = "https://raw.githubusercontent.com/ttab/revisorschemas/refs/tags/{{.Version}}/{{.Name}}.json"

Document types

Document blocks are used to configure document types.

• meta_doc string: the document type that should be used for meta documents, optional.
• statuses string slice: all the statuses that are valid for the document type.
• workflow object: defintion of the workflow for the document, optional.
• attachment block: attachment configuration with name (label), required (bool), and match_mimetype (string slice).
• bounded_collection bool: whether the document type is a bounded collection (finite and small number of documents).
• evict_noncurrent_after int: evict non-current document versions after this many seconds, optional.
• time_expression object: time expression used to extract timestamps.
• label_expression object: label expression used to extract labels.

Workflow object

• step_zero string: the workflow step that a document starts on, and reverts to after a new revision is created after a checkpoint status.
• checkpoint string: the name of the status to use as a checkpoint step, usually "usable" to signal that something is published.
• negative_checkpoint string: the checkpoint name to use when the checkpoint status is set with a negative version.
• steps string slice: the statuses that should be used as steps between checkpoints.

Example

document "core/article" {
  meta_doc = "core/article+meta"

  statuses = [
    "draft",
    "done",
    "approved",
    "withheld",
    "cancelled",
    "usable",
  ]

  workflow = {
    step_zero  = "draft"
    checkpoint = "usable"
    negative_checkpoint = "unpublished"
    steps      = [
      "draft",
      "done",
      "approved",
      "withheld",
      "cancelled",
    ]
  }
}

Metrics

Metric blocks are used to configure metric kinds:

metric "charcount" {
  aggregation = "replace"
}

aggregation can be "replace" or "increment", defaults to "replace".

Usage

All changes to schemas require lockfile update. So the first thing you have to do for a new configuration directory is to run the update command. This will not change anything in the repository, but will check that the referenced schema versions exist and update the lock file.

eleconf update -dir examples/tt

To apply the configuration to a repository installation run apply:

eleconf apply -env stage -dir examples/tt

The apply command accepts --env to select the environment configuration, and optionally --client-id and --client-secret for client credentials authentication. The repository endpoint is resolved from the environment configuration.

This will compare the current configuration with the one declared in the configuration directory, detail the changes, and ask for confirmation before applying.

Example use:

❯ go run ./cmd/eleconf apply -dir tt

~ schema downgrade tt v1.1.1 => v1.0.5-pre1
 Warning:  downgrading schema
+ status "print_done" for "tt/print-article"
- status "nonsense" for "tt/print-article"
~ update workflow for "core/event":
  &eleconf.DocumentWorkflow{
  	StepZero:           "draft",
  	Checkpoint:         "usable",
  	NegativeCheckpoint: "unpublished",
  	Steps: []string{
+ 		"draft",
  		"done",
  		"cancelled",
  	},
  }


Do you want to apply these changes? [y/n]: y

~ schema downgrade tt v1.1.1 => v1.0.5-pre1
+ status "print_done" for "tt/print-article"
- status "nonsense" for "tt/print-article"
~ update workflow for "core/event"

Configuration has been updated