Help › Guide

Reconciliation checks

Reqlyn 0.5.1 is not released yet. This help describes it ahead of release.

Two systems often hold the same records: an inventory and an IPAM both know each device's address. A reconciliation check reads both through operations you already have, matches their records by an exact key, and says where they disagree. It writes to neither. A correction is a separate step that you, or on a server a second person, approve.

A check

A check is a small file:

reqlyn: 1
check:
  name: inventory against ipam
  left:
    operation: Inventory devices
    step: devices
    items: items
    key: address
    label: inventory
  right:
    operation: IPAM addresses
    step: addresses
    items: items
    key: address
    label: ipam
  fields:
    - name: device
      left: hostname
      right: device
      owner: left
      fix:
        operation: Correct IPAM device
        key: address
        value: device
  fresh:
    side: right
    at: updated_at
    most_days: 90
  • left and right: each side's operation, the step whose response holds the records, where the list is in that response (items; empty when the response is the list), the field each record is known by (key) and what the side is called in findings (label). A check reads the records a step received, not the operation's output.
  • fields: each field both sides hold, its name on each side, and which side owns it, whose value is right. fix, when there is one, names the operation that writes the owner's value to the other side, and which of its inputs take the record's key and that value.
  • fresh: how old one side's records may be, by a field holding when each was last changed (RFC 3339).

Running it

reqlyn check save inventory-ipam.yaml
reqlyn check list
reqlyn check run "inventory against ipam"

run runs both operations on this computer and prints, each with its record and where it came from:

  • matched: the same key on both sides, owned fields agreeing;
  • missing: a key held by one side only;
  • duplicate: a key held twice on one side (its fields are then not compared);
  • conflict: an owned field that disagrees, with both values and the side that owns it;
  • stale: a record older than fresh allows.

Only exact keys match. Nothing is matched by being similar.

On the desktop

Checks, the shield on the rail, lists the checks kept on this computer. Choosing one runs it and shows a summary ("4 inventory and 5 ipam. 6 to review, 0 dismissed. Nothing was written to either.") and each finding as its kind, its key and a sentence.

  • Keep or Dismiss each finding; dismissed ones are behind "Show dismissed", and Undo takes either back.
  • Pairing: "Not the same record" unpairs a match; "Pair them" pairs two records whose keys differ, and "Unpair" undoes it. Reqlyn suggests near-misses (keys equal once case and separators are set aside, or records holding the same owned value), but a suggestion changes nothing until you pair it.
  • Plan fixes, for a check whose fields name fixes: runs the check again and lists, under PLAN, each write as a sentence, "through <operation>", and what it would send; each finding not planned says why (a missing record is for a person to add or remove; which of a duplicate is right is a person's call; an old record is confirmed by its owner). "Write it" (or "Write all N") sends the writes one after another, then runs the check again: each written finding reads "Resolved", "Unresolved, written and found again" or "Unresolved, not written" with why.

Overrides and reviews stay on this computer.

On a server

A check can be published over two published versions that only read, in one environment:

reqlyn remote check publish inventory-ipam.yaml --environment lab --versions 3 2
reqlyn remote checks
reqlyn remote check show "inventory against ipam"

The check asks for no run itself. Each time either side's version succeeds in that environment (schedule both to keep it fresh), the server keeps that side's records, sealed, and reconciles them against the other side's last records, keeping the last twenty results with when each side was read. Reading findings is an editor's, as they hold what both systems' responses held.

Plans and approval

reqlyn remote check plan "inventory against ipam"
reqlyn remote plan show <id>
reqlyn remote plan approve <id>
reqlyn remote plan outcome <id>

check plan turns the last conflicts into a plan of writes, each through the fix its field names (a published version activated in the check's environment), with a preview of what it sends; nothing is sent. A plan is approved or refused once, by a publisher signed in as a person who neither proposed it nor issued the token that did; a service token never approves. Approved, each write's run is asked for once. plan outcome says, finding by finding, whether each was resolved (the next reconciliation read after the write no longer finds it), unresolved, skipped or uncertain, with why.

Help for Reqlyn 0.5.1. All help topics