Table of Contents

Technical Design

How the Empower Companion is built, packaged, and deployed. It follows the same principles as the backend packages: delivered through the Catalog, data in DOM, and no manual setup for participants.

Note

This is a proposed design. Items marked (verify) must be validated on the target DataMiner version before the dry run.

Components

Component Purpose
Catalog item Empower – Companion Installs everything below. Deployed once per DataMiner System, together with the vertical packages.
Companion app Static frontend app in Webpages\public\empower-companion\, opened through DataMiner sign-in
DOM module empower_journey Stores events, journeys, app versions, and feedback
Companion scripts Automation scripts that save progress, check the backend, publish apps, and send the summary
Journey content Per vertical: problem cards, cheat sheets, examples, starter prompts, knowledge pack extracts, and design card examples
Reference apps Per vertical: one app that solves all three problems, as a deployable build and its source, to build further on in session 4 (C-09)

The companion package is separate from the vertical packages so it can be updated without touching the backend, and so it is deployed only once on systems that host several verticals.

Architecture

flowchart LR
    P[Participant browser] -->|/auth/?url=…| CA[Companion app<br/>public/empower-companion]
    CA -->|GQI: read| DOM[(DOM<br/>empower_journey)]
    CA -->|Execute Automation script| SCR[Companion scripts]
    SCR -->|write| DOM
    SCR -->|check| VB[Vertical backend<br/>DOM · services · elements]
    SCR -->|publish| PUB[Webpages\public\<br/>participant apps]
    SCR -->|send| MAIL[Email<br/>jarne.vynckier@skyline.be]
    P -->|link| PUB
Interaction How Reference
Sign-in The app is opened through /auth/?url=…, so it has a DataMiner session DataMiner Web Services authentication
Read journey data GQI query on the empower_journey DOM module, filtered on the signed-in user GQI – DOM instances
Write journey data and actions Automation scripts executed from the app; scripts validate input and write to DOM ExecuteAutomationScriptWithOutput (verify)

Writes go through scripts so validation, permissions, and file system access stay on the server.

Data Model

DOM module empower_journey:

Definition Key fields Notes
Training Event Name, date, format (in person/online), current step (trainer marker), summary recipient (default jarne.vynckier@skyline.be), trainer user group One per event. Set up by the trainer.
Participant Journey DataMiner user, display name, company, email, consent, event (link), vertical, chosen problems, problems built now, level, end state, Outcome Canvas answers, 30-60-90 per horizon, path into session 4 (own app/reference app), agent design card, next increment, completed steps, used catch-up shortcuts, submitted at One per participant per event
App Version Journey (link), problems covered, version number, folder name, link, source (own/reference), uploaded at, status One per upload
Feedback Journey (link), moment (J12/J20/J21), answers One per feedback moment

The journey is linked to the DataMiner user that is signed in, so several participants can share one system. See System Setup.

Companion Scripts

Script Called from Responsibility
Empower_Companion_SaveStep Every step Validates and saves the answers of a step; marks the step as completed
Empower_Companion_CheckBackend J4 Checks that the vertical's DOM module, services, and elements exist and that the Baseline script is scheduled
Empower_Companion_UploadApp J11, J19 Receives the zipped build, validates it, and publishes it (see App Upload)
Empower_Companion_UseReferenceApp J13, J14 Publishes the reference app of the participant's vertical to the participant's folder and returns the link and source. Only available once the trainer marker has reached J13.
Empower_Companion_SubmitSummary J22 Builds the journey summary and sends it by email (see Journey Summary by Email)
Empower_Companion_SetStep Trainer view Sets the current step of the event (trainers only)
Empower_Companion_Reset Manually, after the event Removes participant apps and journey data after the retention period

App Upload

Participants build their app with the AI App Builder and upload the build output. The companion publishes it to the DataMiner public folder and returns a link.

Build Folder Name

Before building (J9), the companion gives the participant a build folder name, for example, empower-<user>-<vertical>. One folder per participant is enough, because one app can cover several problems. The app must be built for that folder: the AI App Builder sets the base path to /public/<build folder name>/. The starter prompt asks for this, or for relative asset paths, so the app also works after upload.

Upload Flow

sequenceDiagram
    participant P as Participant
    participant A as Companion app
    participant S as UploadApp script
    participant W as Webpages\public
    P->>A: Select zipped build output
    A->>S: Send zip (in chunks)
    S->>S: Validate (size, files, paths, index.html)
    S->>W: Archive the previous version
    S->>W: Publish to public\<build folder name>\
    S->>S: Save App Version in DOM
    S-->>A: Link to open the app
    A-->>P: Show link and "Open app"

Validation Rules

Rule Why
Only the journey owner can publish to their build folder Participants cannot overwrite each other's apps
Folder names are generated by the companion, not typed by the participant Prevents path manipulation and name collisions
Maximum zip size and number of files (to define, e.g., 25 MB) Protects the DataMiner System's disk
Entries with .., absolute paths, or drive letters are rejected Prevents writing outside the build folder (zip slip)
Only static file types are allowed (e.g., .html, .js, .css, .json, images, fonts, .map) Prevents server-side or executable content
An index.html must exist at the root, or in a single top-level folder that is flattened Makes sure the link works
index.html must not reference another /public/… folder Detects apps built for the wrong folder, with a clear message

The companion returns a link that opens the app through DataMiner sign-in:

https://<dma>/auth/?url=%2Fpublic%2F<build folder name>%2Findex.html

Opening /public/<build folder name>/index.html directly does not have a DataMiner session.

Versions

The link stays the same for every new upload, so links shared earlier keep working and always open the latest version. Previous versions are archived outside the public folder and listed in the journey summary.

Warning

Files in the public folder can be downloaded without signing in, and uploaded JavaScript runs on the DataMiner origin. Only use the upload on training systems, never on production systems, and remind participants not to put credentials or customer data in their app.

Reference Apps

One reference app per vertical (C-09) that solves all three problems of the vertical in one app. The same app serves two purposes:

  • Session 3: Trainers use it as the answer key. It is not shown to participants before they have explored the data themselves.
  • Session 4: Participants who don't continue with their own app start from it. Because it covers all three problems, it fits every participant of the vertical, regardless of which or how many problems they chose.

This supports different levels: beginners can focus on the part of the app that answers their problem, while advanced participants see a complete example that combines all three.

Part Use
Build output Published to the participant's own build folder by Empower_Companion_UseReferenceApp, so they get their own link
Source Downloaded or opened in the AI App Builder to build further on in session 4 (verify how the AI App Builder imports a project)

The reference app is built with relative asset paths, so the same build works in any participant's folder.

Journey Summary by Email

Empower_Companion_SubmitSummary builds the journey summary and sends it:

Recipient Source When
Training owner Summary recipient field of the Training Event, set to jarne.vynckier@skyline.be Always, after consent
Participant Email field of the journey Only if the participant entered an email address
Item Design
Sending Through the DataMiner System's email (SMTP) configuration, from an Automation script (verify SMTP on the training systems)
Format The journey summary document (Markdown with front matter) as an attachment, plus a short readable version in the email body
Subject Empower journey – <event> – <display name> – <vertical>
Fallback If sending fails, the companion offers the summary document as a download and an "Email this summary" link with the recipient prefilled
Record The submission time is stored in the journey, so trainers see who has submitted

The summary document has a fixed structure so it can be used directly as input for an agent that reviews all summaries of an event. The recipient is stored in the Training Event, with Jarne's address as default, so it can be changed without rebuilding the companion.

Trainer View

Users in the trainer group of the event see an extra view in the companion:

  • Set the current step for the group (the trainer marker).
  • See per participant: current step, completed steps, catch-up shortcuts used, uploaded apps, and submission status.
  • Open each participant's latest app link.

Privacy

Principle Implementation
Minimal data Only a display name is required; company and email are optional
Informed consent J1 explains what is stored; J22 asks for consent again before sending
Data stays on the training system Journey data is stored in DOM on the training system; only the submitted summary leaves it
Limited retention Empower_Companion_Reset removes journey data and apps after the retention period (to define)

Source Repository (proposed)

The companion is added to the Empower solution:

Empower.sln
├── Empower.Common/
├── Empower.Companion/
│   ├── Empower.Companion.Package/       package project → Catalog item "Empower – Companion"
│   ├── Empower.Companion.App/           frontend app → Webpages\public\empower-companion
│   ├── Empower.Companion.Scripts/       SaveStep, CheckBackend, UploadApp, UseReferenceApp, SubmitSummary, SetStep, Reset
│   ├── Empower.Companion.Content/       journey content per vertical (JSON) and the summary document template
│   └── Empower.Companion.ReferenceApps/ one reference app per vertical, solving all three problems (source + build)
├── Empower.Telco/
└── …

Journey content follows the consistency rules: problem cards, examples, and knowledge rules must match the package seed data.

Open Decisions

# Topic Options
1 Upload mechanism (a) Automation script with the zip in chunks (current design) · (b) A user-defined API that receives the zip. Verify the maximum parameter or body size of each.
2 Email route (a) SMTP on each training system (current design) · (b) Send summaries to a central system that emails them · (c) Download and send manually
3 Viewing apps after the event Links only work with access to the training system. Options: add a screenshot to the summary, attach the build zip, or keep training systems available for a period.
4 Base path in the AI App Builder Verify whether the AI App Builder accepts a given build folder name or relative asset paths.
5 Reference app source Verify how the reference app is opened or imported in the AI App Builder.
6 Content source Keep journey content as JSON in the package, or generate it from this documentation site to avoid duplication.

Readiness Checklist

Per training system:

  • [ ] Empower – Companion deployed from the Catalog, after the vertical packages
  • [ ] Companion opens through /auth/?url=%2Fpublic%2Fempower-companion%2Findex.html for every participant account
  • [ ] Training Event created with the summary recipient (jarne.vynckier@skyline.be) and trainer group
  • [ ] J4 backend check is green for every deployed vertical
  • [ ] Test upload: an app built with the AI App Builder publishes and opens through the returned link
  • [ ] Reference apps publish and open for the verticals of this event
  • [ ] Test submission: the summary document arrives at jarne.vynckier@skyline.be with the expected front matter
  • [ ] Trainer view shows all participants