Skip to content

Context Change Requests

The Semantic Layer changes only through a Context Change Request: a proposed change to one or more Context Entries that someone reviews before it applies. Nobody, the agent included, changes an entry any other way.

Two Rights, set per Data Source in the Data Studio, decide it. Neither gives access to the Data Source’s data. See Who sees a Data Source.

  • Create Context Change Requests: you may propose changes to entries linked to that Data Source. A request needs it on every Data Source its entries are linked to, before and after the change.
  • Accept Context Change Requests: you may accept, reject and edit requests. Accepting needs it on every Data Source the request’s entries are linked to, before and after the change, so that nobody changes what others are responsible for.

A request touches at most 50 entries, each with one kind of change:

  • Add: a new entry;
  • Change: new content for an entry;
  • Delete: the entry leaves the Semantic Layer; its versions are kept, and its page stays: whoever could see the entry reads it as deleted, with when and through which request, its last version and its History. Once an entry is added at its path again, the page is the new entry’s, and the deleted entry’s page and History are gone;
  • Link: the entry links to other Data Sources; its content stays as it is.

Accepting applies every change of it or none: the Semantic Layer is never half-changed.

When you tell the agent what a term means or correct how a metric is calculated, it offers to record it as a Context Change Request, so that the correction outlives your Conversation and reaches your colleagues. When it isn’t clear whether you stated your own preference or what something means for your business, it asks you which: a preference goes into your Memory, business meaning into the Semantic Layer. It never keeps business meaning as a memory or in a Skill alone, and never claims it is stored anywhere else.

If you agree, the agent reads the current entry, writes its whole new content or a new entry, and asks for your Approval. The card, Propose a change to the Semantic Layer, shows:

  • who will review it: someone who may accept Context Change Requests on the Data Sources it links to;
  • the agent’s explanation, under Why;
  • each entry with Add, Change, Delete or Link: its lines compared with the version the agent read, every line removed for a deletion, and the Data Sources a link moves it to.

Accept it, and the request opens: the card says Request opened with Open in the Data Studio. Nothing in the Semantic Layer changes until a reviewer accepts it, and the agent says that it proposed the change, never that it saved it. Reject it, and nothing is opened.

The agent can’t open the request when you don’t hold the Right to create Context Change Requests on the Data Sources: it then tells you who could record it. It doesn’t open it either when an entry changed since the agent read it, or when the files aren’t valid entries; the card says why, and the agent can try again.

If you may propose changes, an entry’s page in the Data Studio has Edit, and the Semantic Layer page has New entry.

  1. Edit opens the entry in a text editor. It checks the file as you type and shows Valid or the problems it found. For a Data Model, switch between YAML and Preview, its readable view. Below the text, choose the Data Sources the entry links to, among those you may propose changes to. An entry whose content you leave as it is and whose Data Sources you change is proposed as a link.
  2. For a New entry, choose its Kind, a Short name of lowercase letters, digits and hyphens, such as active-customer, and its Data Sources.
  3. Select Done. Your change goes into your draft, and the entry shows Draft with Discard my changes.
  4. To take an entry out of the Semantic Layer, select Delete on its page and confirm with Add to draft. The entry shows Deleted in your draft and stays as it is until a reviewer accepts the request.

Edit as many entries as you need: the bar at the bottom says how many are in your draft. Your draft is kept in this browser, for you and this Tenant, and survives a reload; if the browser can’t keep it, the bar says so, and you should submit before you leave.

When you’re ready, select Review draft. The draft page lists each entry with Add, Change, Link or Delete, whether it is valid, and its changes. Remove single entries or discard the whole draft. Write an Explanation: what changes and why, and any open question with who might know. Then select Submit as a Context Change Request. A draft holds at most 50 entries.

If an entry changed after you started editing it, the request is created as Stale: the page says so, and you move it onto the current versions (see below).

Select Import on the Semantic Layer page to bring in work done elsewhere as one request:

  1. Files: choose or drop a ZIP of an OKF bundle, OKF Markdown files (.md) or Ossie models (.yaml, .yml).
  2. What they become: each file shows as New, Changes the current entry or Invalid. Leave out the files you don’t want. Generated files, such as index.md, aren’t imported. An entry of a kind that isn’t one of the five keeps its kind.
  3. Data Sources: choose the Data Sources every imported entry links to. They replace the data_sources an entry brings along. A Data Source has at most one Data Model, so an import can change its Data Model but not add a second.
  4. Explanation and request: say where the entries come from and why, and select Open request.

You need the Right to create Context Change Requests on every Data Source you choose.

On an entry’s History tab, open an earlier version and select Revert to this version. It opens a request whose content is that version. See See an entry’s history.

On the Semantic Layer page, select Context Change Requests, then My requests. Each request shows its state:

  • Open: waiting for review;
  • Accepted or Rejected, with who decided, when, and their comment;
  • Withdrawn: you took it back;
  • Stale: see below.

Open a request to read it. To take back an open or Stale one, select Withdraw and confirm; it can’t be reopened.

If you may accept Context Change Requests, the Data Studio counts the requests waiting for you next to Semantic Layer, and the Web App’s app switcher shows the count on the Data Studio. Select Context Change Requests, then To review, for the oldest first.

A request’s page shows who opened it and when, its Data Sources, the explanation, and each entry with Show the changes: the lines added and removed against the version it was based on, for an OKF file and a Data Model alike. A new entry shows every line as added, a deleted one every line as removed, and a link says that only its Data Sources change. Once a request is accepted, Open the entry leads to each of its entries, a deleted one too, unless its path was added again: then it opens the new entry.

  • Accept applies all its changes. Add an optional Comment for the proposer first.
  • Reject closes it with your optional comment. The proposer sees who rejected it and why.
  • Edit lets you correct the request before you accept it, so that you don’t send it back for a typo. Your edits are checked like any entry, become part of the request, and the request shows who edited it. If you change a Verified Query, you are recorded as the one who confirmed it, with the date. A deletion or a link has no content to edit.

If you lack the Right to accept on one of its Data Sources, the page says which, and that the request waits for someone who holds it.

A request is Stale when one of its entries changed after it was opened, for example because another request on the same entry was accepted first. It can’t be accepted, so a later change never silently overwrites an earlier one. If two reviewers accept requests on the same entry at the same time, one wins and the other request becomes Stale.

A Stale request can still be rejected or withdrawn. Its proposer can select Move onto current versions: this opens a new request with the same changes and explanation on the current versions, and the Stale one stays as it was until it is rejected or withdrawn.

A request that links an entry to a Data Source that is deleted meanwhile becomes Stale too. Moving it onto the current versions leaves the deleted Data Source out.

Every request opened, accepted, rejected or withdrawn, and every revert, is recorded in your Tenant’s Audit Log, with the request’s ID and never its content. When a user leaves your Tenant, their open requests are withdrawn, and their name is taken out of the requests and versions they proposed or decided.