Gå til hovedinnhold

Explore your context

Goal: read a project's context the way you would read a dashboard. You follow the KapiMart sample's rules and content across the axes the project declares, move a window through time, find the rules that hold only for a while, and compare two moments.

You need Kapi Desktop and the KapiMart sample. Nothing in this recipe runs a model or changes the project. For what each section of the app is, see the overview.

What the sample declares​

The sample's kapi.yaml declares four axes beside the product and the channel. The market is a geo axis. Its values are places: the built-in countries and counties, and the places the recipe declares:

places:
  nordics:
    name: Nordics
    of: [no, se, dk, fi, is]
  oslo:
    name: Oslo
    type: locality
    within: no-03
    centroid: [59.91, 10.75]
  grunerlokka:
    name: Grünerløkka
    type: neighbourhood
    within: oslo
  greater-oslo:
    name: Greater Oslo
    type: metro
    of: [no-03, no-32]

axes:
  market:
    kind: geo
    label: Market
  audience:
    label: Audience
    values: [shoppers, developers, partners]
  age:
    kind: range
    label: Reader age
    unit: years
  lifecycle:
    kind: ordered
    label: Lifecycle
    values: [preview, current, sunset]

The axis kind determines whether a rule at one value applies to content at another. A rule for the Nordic market holds in Norway and in Oslo. A rule for readers aged 13 to 17 holds in content written for readers aged 14 to 16. The project file reference lists the kinds, and Place content in markets and areas covers places.

An Oslo youth campaign sits at market: oslo and age: 13-17, with its pick-up page at Grünerløkka. The sample includes the two assistant sessions you review in Review what your assistant noticed. It also includes six notes that a teammate recorded and kept. One holds in Japan, one for readers aged 13 to 17 and one for the Oslo campaign's readers. Three hold for a limited time: one is in force today, one has ended and one starts in 20 days.

Steps​

  1. Open the sample and its Explore section. On the home, click Try the sample, then open KapiMart and choose Explore in the Context hub. The page opens on the last 30 days, with the snapshot at today.
  2. Read the timeline. Each bar counts the records of one day: terms added to the terms store, notes and decisions. Drag across the timeline to choose another window, or pick 7d, 90d or All. The counts under the timeline cover the window: records in scope, units of content, records that need a person, and records that changed state.
  3. Trace a value through the flow. Flow opens with four columns: family, product, channel and state at the snapshot. Hover Rule in the first column. The same records are highlighted in every column, which shows the channels where the rules were seen and the state of each. The scope stays as it is until you click.
  4. Keep a selection. Click Contested. It becomes a chip under Scope, and every view shows only those records. Shift-click Suggested to add it. Values of one axis combine with or, and values of different axes with and. Clear filters empties the scope.
  5. Change the columns. Use a column's menu to show another axis, such as Market or Reader age. Use Column to add a column, and the arrows to move a column left or right.
  6. Find the rules that hold for a while. Under Try a question, choose Rules with a lifetime. The first column becomes Lifetime: one note In force, one Expired and one Upcoming. Select one to open it beside the view. The pane shows the scope it holds at, when it was recorded, the window it holds for, its history and the sentence it was seen in.
  7. Switch the clock. Set Clock to Effective. With this clock, the timeline places a rule at the dates its window opens and closes, and ignores the day it was recorded. The timeline then shows when the context changed. A window that opens after today is counted beside the legend as outside the span.
  8. See where the markets are. Open Map. It opens on the Nordics, the narrowest area that contains the places the recipe declares and the places its content sits at. Norway is filled, because the Oslo campaign note is placed inside it. The other four countries are hatched, because the winter campaign note is placed in the Nordics and holds in each of them. For each place, the list beside the map counts the records placed there (Here) and the records held there through a wider place (Held). The records at World form one Held everywhere count. Select World in the path above the map to draw every country: Japan and Germany are filled, because notes are placed there. Hover Nordics to outline its countries. Click Norway to drill into its counties, and hover Greater Oslo to outline the two counties it is made of. Click the county of Oslo to show the places the recipe declares in it. The city is drawn as a circle at its centroid. Use the path above the map to go back up. To keep only the records that hold in one place, select the place in the list. Grid draws one tile of equal size per country, so tile area is unrelated to land area.
  9. Read state over time. Open Over time. Each row is one value of an axis and each column is a stretch of the window. A cell's colour is the share of records that need a person at the end of that stretch.
  10. Compare two moments. Click Pin A. Move the window back a month, then choose Compare with A. Both sides keep the same order of values and the same scale. The counts give the number of records on only one side, and the number of records on both sides whose state changed.
  11. Take the investigation with you. The download button saves the query, the pinned side, the selected record and the counts as JSON. A teammate or an assistant can read the file to see what you were looking at.

The same on the command line​

kapi context atlas                          # a summary: axes, records, span
kapi context atlas --json                   # the data Explore reads
kapi context log <id>                       # one rule and every decision about it
kapi context note "Prices include tax." \
  --seen-in src/en/store-ui.json --quote "Estimated Tax" \
  --point market=jp --valid-to 2027-01-01   # holds in one market, for a while

A note's --point can only narrow the place where its evidence was seen. A note seen in the store's strings can be placed in Japan. Placing it more widely is a person's decision in review. --valid-from and --valid-to take a date or an instant. The window includes its start and excludes its end.