Sample data

Some apps ship sample data: a few example records in the app’s own tables, so a new install has something to click through. Adding it is always your choice, and taking it out again removes only what it added.

Adding and removing sample data needs the Install and manage apps and add-ons permission.

Adding it

There are two ways in:

• At install. The Sample data box on the table check reads Add sample data and is not ticked. When you tick it, the records are added after the install has finished. If that part fails, the app stays installed and you can add the data later.
• Later. On the app’s settings page (Studio → Hosted apps, then the app’s name), the Sample data card shows Not loaded and an Add sample data button.

The dialog says how many records go into each table, how many images go to Files, and the total, before anything is written. Nothing else in the database is touched.

What happens when you confirm:

• All or nothing. Every record is written in one transaction. If one is refused, nothing is written and the dialog says which table refused it.
• Beside your records, never over them. Sample records are added as new rows; they never replace or change a record you already have.
• Your codes and numbers stay yours. When a sample record carries a code or a running number that a row in the table already has, the sample’s value is dropped and the column’s own rule fills in a fresh one, exactly as for a record a person creates. A sample record that leaves a code empty gets one too, so a sample handover link opens. The code a shared link opens a record by is always made fresh: one printed in the app’s package would open the same sample page on every install. See Column rules.
• Your settings stay yours. A sample row meant for a table that holds one row, such as the app’s own settings, is added only when that table is empty. When you already have a row there, the sample leaves it alone and uses it.
• One of a kind stays one of a kind. Any other column that must be unique (a weekday’s opening hours, a day already closed) is never worked around: if a sample record would repeat a value one of your records holds, nothing is added, and the dialog names the table, the column and the value. Sample data is meant for tables that hold none of your own records of that kind yet.
• Rules apply, automations do not. The records go through the same column rules as a person’s write, but no hooks or automations run, so a sample booking sends no email.
• Images go to Files. A picture the sample uses is stored in the Files library under the app’s connection, like any other upload. See Attaching files to records.
• Two apps’ samples do not double a shared table. When another installed app’s sample already put the same row in a table the two apps share (the same @label, the same values, still as that sample wrote it), the row is taken as this app’s sample row too and not written again: a copy of an app beside its original shows one menu, and the copy’s sample orders are of the dishes already there. Removing one app’s sample leaves such a row in place for the other; it goes when the last app that lists it removes its sample. A row that differs (a dish at another price), or that you changed since, is left alone and the app writes its own beside it.
• A shared menu keeps its real dishes. An app that shares a table with another app can leave its sample rows out once that table holds real ones. See A menu two apps share.

The card then reads Loaded, with the number of records and the date. An app’s sample data can be loaded once at a time: remove it before adding it again.

Sample times that follow the calendar

Sample times are written relative to the moment the data is added, on the venue’s clock, so a sample never looks stale. Three forms keep it believable whatever day and hour that is. The fields are in the manifest reference.

• Days that keep their weekday. A hotel’s sample has a weekend stay. With {"@day": 3, "@week": true} its days count from the bundle’s weekAnchor (a weekday such as "tue") in the week nearest the adding day, at most three days either way. Added on a Tuesday or a Thursday, the stay still arrives on a Friday. A @week day needs the bundle to name its anchor.

• A status that matches the clock. @byStay sets some of a row’s columns by where the adding moment falls against its two times: before the stay, during it, or after it.

  {
    "arrive": { "@day": 3, "@week": true },
    "depart": { "@day": 5, "@week": true },
    "@byStay": {
      "from": "arrive",
      "to": "depart",
      "times": { "from": "15:00", "to": "11:00" },
      "before": { "status": "booked" },
      "during": { "status": "in_house" },
      "after": { "status": "departed" }
    }
  }

  from and to are columns of the row, or times written in place. A date is read at the times given (arriving from 15:00, leaving by 11:00), else at its midnight. A set with "@skip": true leaves the row out. A row takes @byStay or @byClock, not both.

• A time the venue is open. A pickup order 20 minutes from now is no use at 21:10 when the kitchen closed at 21:00. {"@in": "PT20M", "@slot": "orders"} is the first open time of that table’s slot limit at least that far ahead: its hours, closures and pauses, on its grid. It counts the rows already there and the sample rows placed so far, so a time that is full is passed over. When today has no open time left, it is the next day the venue opens. It looks about two weeks ahead, and a limit with no open time in reach keeps the plain time. The table must keep a slot limit, and @slot takes no @grid of its own.

Sample rows are real rows to the app’s rules. A sample pickup order takes its place in the slot it lands on, and a sample stay takes its room for its nights, so guests see that much less on the customer pages. Remove the sample data before you open for real.

Rows for an add-on the app names

An app may ship sample rows for the tables of an add-on it names, in a file of their own:

"sampleData": { "file": "seeds/sample.json",
                "addOns": { "stock-kit": { "file": "seeds/stock.sample.json" } } }

The file says which add-on it is for ("addOn": "stock-kit") and lists that add-on’s tables by their short names. A table of the app itself that links into the add-on goes in the same file, marked "own": true. A row may point at a row of the app’s own sample or of the add-on’s own sample by its label ({ "@ref": "…" }), and name one of the app’s tables with { "@table": "orders" }.

These rows are added with the app’s sample while the add-on is installed in the same database, connected to the app and switched on. They are listed as the app’s, and removing the app’s sample takes them out again. A file that names rows of the add-on’s own sample waits until that sample is loaded, and is taken out before that sample is, own rows and all.

An app never ships an add-on’s history: what was counted is the add-on’s to write. A movement, a level, a reservation, a balance, a receipt — any table a total adds up, or that holds a total — is refused in the file. What an add-on’s ledger writes beside its books is not history, and an app may ship it: the rows that say which of the app’s rows uses which of the add-on’s (Inventory’s links: “this visit type offers the flu kit”, “this dish uses these items”).

{ "format": "adminium.sample/1", "app": "clinic", "addOn": "inventory",
  "tables": [
    { "ref": "links", "rows": [
      { "source_table": { "@table": "appointment_types" }, "source_row": { "@ref": "type:nurse" },
        "kind": "kit", "kit_id": { "@ref": "kit:flu-vaccination" }, "qty": 1 } ] }
  ] }

Adminium reads which tables those are from the add-on’s own manifest: a table is one when no total adds its rows up, it holds no total itself, and every action of the ledger that writes it writes only such tables. Such a row never fills the link to a posting’s receipt.

While it is loaded

The app’s own pages in the dashboard show Sample data is loaded at the top, with Remove it. Only people who can manage apps see this line.

Adminium keeps a list of every record and image it added, in a table of its own in the app’s database, named after the app’s key with _sample_data at the end (for example pos_sample_data). The Data card lists it as “Adminium’s list of sample records”. It is made the first time you add sample data, and it is left out of the app’s pages and of the public API.

Removing it

Remove sample data on the card, or Remove it on the banner, opens a preview first:

• Removes — how many sample records go, per table.
• Kept — the sample records you have made your own:
  • a sample record one of your own records uses is always kept, with the records it points at in turn. Removing it would break your record;
  • a sample record you edited since it was added is kept while Keep the ones I changed is ticked, which it is by default. The preview names them. Untick the box to remove them too.

Remove then deletes the rest in one transaction. If the database refuses a delete because something still points at a sample record, nothing is removed and the message names the table.

When it is done:

• Kept records are yours. They leave Adminium’s list and are never treated as sample data again.
• The list ends empty, so the card reads Not loaded and Add sample data is offered again. Adding it again starts afresh.
• Images follow their records. An image goes to the trash in Files unless a kept record still uses it, and is deleted for good like any other trashed file.

A message on the card says how many sample records stayed, if any.

Rows a ledger’s receipt names

A sample row that posted into an add-on’s ledger is named by that ledger’s receipt, as text. Remove sample data keeps such a row, as it keeps one a real row links to, and says how many it kept — unless the receipt is itself a sample row of the same removal, when both go. The balances the kept rows feed are added up again.

Sample rows are brought in as history: creating them posts nothing and is never refused by a ledger.

On uninstall

Uninstalling an app does not remove its sample data on its own: the records are rows in the app’s tables, and those tables are kept unless you choose to delete them. See Uninstalling. To start clean, remove the sample data before you uninstall.