Walkthroughs

Walkthroughs

Screenshots are captured in a reference environment and may show sample data or a theme that differs from your tenant.

Three tasks, in the order you will do them. Each is complete on its own.

---

Walkthrough: Install the schema

Who: platform administrator · Prerequisite: a Fuuz tenant dedicated to one Plex PCN

1. Download plex-keyring-schema-0.6.0.tgz from the repo. The .fuuz file beside it is the same schema exported from a live tenant — either works.
2. In Fuuz, open Package Management and import the archive.
3. Wait for the install to complete. It creates 182 data models and deploys them.

Verify: query any model — plexPart, plexCustomer, plexSupplier — and confirm it exists and returns an empty result rather than an error.

If it fails on "a record already exists": the installer creates models, it does not upsert them. A tenant that already carries a plex* model from an earlier install must have it removed first. This is the most common install failure and it is not recoverable by re-running.

---

Walkthrough: Make the schema usable

Who: platform administrator · Why: two things must exist before a single row can be written

1. Register the source system

Every row carries sourceSystemId as a real, enforced relation to ExternalSystem. Until that row exists, every insert is refused — on the first row, not the millionth.

Create an ExternalSystem record identifying this Plex instance, for example code PLEX-HOU.

Verify: the record is visible in the External System list. A mistyped id will now be rejected at write time rather than discovered later under a name nobody recognises.

2. Declare the site identity

If you are also installing the extraction flows, they read the PCN and source system from tenant configuration and refuse to run until both are set. Loading a million rows under the wrong identity is not recoverable by re-running, so the flows decline rather than guess.

Verify: plexKeyringGets.site.pcn and .sourceSystemId are both populated.

---

Walkthrough: Load data in the right order

Who: integration engineer · Prerequisite: extraction flows installed (separate package)

Load order is a correctness requirement, not a preference. Foreign keys target id and are enforced, so an endpoint whose parent has not loaded yet is a rejected write — and rows go up in batches of 500, so one bad reference fails the whole batch.

Each endpoint publishes a loadLayer. Run layers in ascending order:

Layer	Endpoints	Contains
0	60	Things nothing else depends on — parts, buildings, users, suppliers
1	16	First dependants
2	31
3	35
4	30
5	9
6	1	Deepest — everything it references is already loaded

There are no cycles in the relation graph, so a total order exists and every child sits strictly after its parents.

Verify: after each layer, check row counts moved. A flow returning SUCCESS means a request completed, not that data arrived — a disabled endpoint, a sub-resource whose parent is empty, and an upsert that matched an existing row all return success and land nothing. The row count is the evidence.

---

Walkthrough: Turn on the endpoints you need

Who: integration engineer

All 182 endpoints ship disabled. The package carries full coverage so nothing has to be rebuilt when a site needs one more object; the site turns on only what it uses.

1. Open the plexKeyringGets application configuration.
2. Set enabled: true on the endpoints you need.
3. Leave the rest off.

Each entry also carries pageSize and intervalMinutes per endpoint, because a part master and a container feed do not deserve the same cadence.

Verify: the endpoint's model gains rows on the next run. If it returns success and lands nothing, check that it is enabled — that is the usual cause.