Skip to main content

Create or Edit a Model-Driven App

Goal​

Build a Model-Driven App — a named app that groups a chosen set of the environment's tables, Studio screens and reports into a navigation (site map) with a home page, ready for a user to open in the Platform Shell — or change an existing app's name, navigation, or home page.

Prerequisites​

  • You are signed in with a maker (or platform administrator) role.
  • The tables the app will show already exist in the environment (see Create an Entity), and so do any Studio screens (Draw a Studio App) or reports (Create a Report) you want in its navigation.
  • You know the owning publisher's prefix (for example, par). The app's logical name must start with that prefix.

Steps​

  1. In the left sidebar, choose the environment you are working in and the solution the app belongs to from the environment and solution pickers. The owning publisher's prefix appears beneath them (for example, par_); the app is namespaced by it.
  2. Open Apps from the sidebar navigation. The page shows the environment's apps as a list.
  3. Select New to create an app, or select an existing app's row and then Edit to change it. Either way, a panel opens at the side of the screen with the app's details.
  4. Enter a display name (for example, Sales).
  5. For a new app, enter a logical name that starts with the publisher's prefix — for example, par_sales_app. When editing an existing app, the logical name is shown but cannot be changed.
  6. Optionally enter a description (shown on the app's launcher tile) and an icon key.
  7. Build the app's navigation. Each navigation group has a title, and under it a row of buttons — one per kind of destination: Add table to navigation, Add report to navigation, and Add screen to navigation. Each button opens a searchable list of that kind; type to narrow it by either the name you gave the destination or its logical name, then select one to place it. A button only appears when the environment has something to put in it, so an environment with no reports shows no report button. Any placed item can take an optional label override and icon, and can be removed. To reorder the items in a group, drag a row by the grip handle on its leading edge — the order you leave them in is the order the app's navigation shows. Without a mouse: focus the grip, press Space to pick the row up, the arrow keys to move it, and Space again to drop it. Select Add group to add another navigation group.
  8. Optionally choose which forms and views this app offers for a placed table — see Choosing what the app offers for a table below. Under each placed table's name the row says what the app currently offers ("3 forms · 2 views", or "2 of 5 forms" once you have narrowed a list), and the sliders button opens the choice. A dashboard's row and a report's row say which of the three they are instead, and have no sliders button: neither has forms or views to choose between.
  9. Choose the app's home page — what opens when a user starts the app, and where the rail's Home entry goes. It can be a table, a Studio screen, or a report, and the list offers only what you have placed in the navigation. A screen here is how an app opens on live numbers rather than on a grid of rows.
  10. Select Add app (or Save, when editing). The panel closes and the list refreshes with your changes.
  11. Give the app to the people who will use it. Building it does not share it: a new app is visible to makers and administrators and to nobody else. Select the app's row and then Share — see Give an App to the People Who Will Use It.

Screens and reports in an app​

A navigation item is a destination, and there are three kinds:

  • A table opens its list, and the records, views and forms behind it.
  • A Studio screen takes the whole content area — what you drew is the screen.
  • A report opens the report viewer over the whole table, ready to print. (A report run from a record's form or a view's command bar carries that record or that filter; one opened from the navigation does not, because there is nothing on screen for it to carry.)

Each has an address of its own, so any of them can be bookmarked, shared, refreshed and pinned: /apps/{app}/{table}, /apps/{app}/dashboard/{name}, /apps/{app}/report/{name}.

Who may open one is a permission. Opening a screen and running a report are grants held by a security role like any other permission. A user without the grant sees the item in the rail and is told they may not open it, rather than being shown somebody else's numbers. Separately, everything a screen and a report's datasets read is filtered by the reader's own record permissions — so two people opening the same screen see the records each of them may see.

Dashboards are retired

The platform used to offer a dashboard — a grid of KPI, chart and view widgets — as a fourth kind of destination, and the Application Studio replaced it: a drawn screen does everything a dashboard did, and it is the canvas you are already learning. So there is no Dashboards list, no dashboard designer, and no Add dashboard button. An app that already names one still opens it and its permission still applies — nothing stored has changed — but a new one is drawn as a Studio screen. See Draw a Studio App.

Choosing what the app offers for a table​

A table accumulates forms and views over its life — an admin form beside the one a salesperson uses, a "My open items" view that only matters to one team. An app that shows every one of them is how a clean table becomes a cluttered app.

Select the sliders button on a placed table's row (Forms and views for table) to open the choice. Each list is either:

  • Every form of this table, including ones added later — the app follows the table. A form you add to the table tomorrow appears in this app automatically.
  • Only the ones selected below — a fixed choice. A form added to the table afterwards does not appear in this app until you come back and tick it.

That difference is the whole point of having both, and it is not the same as ticking every box: a maker who curated an app's forms rarely wants the next one to turn up in it unannounced, and a maker who curated nothing always does. Switching to Only the ones selected starts with everything ticked, so you remove what you do not want rather than rebuilding the list.

Unticking everything does not hide the table — a table with no form could not be opened — so it saves as "every one", and the dialog says so while you are in that state.

The selection decides which forms and views the app offers, not the order they appear in or which one opens first. Those stay the table's own.

The counts under the table's name say which state it is in without opening the dialog: 3 forms · 2 views is a table the app follows, and 2 of 5 forms is a list you closed.

Split a long navigation into areas​

Beside each group's title is an area box. Give groups the same area — Front desk on Bookings and Customers, Settings on Configuration — and once two or more areas are named, the app's navigation shows one area at a time, with a switcher at its foot. Leave the box empty for a group every area should show, such as a home page or Today. With no areas named, the navigation is unchanged.

What happens behind the scenes​

The app is stored as metadata scoped to this environment and namespaced by the publisher prefix, as a component of the selected solution. Its navigation references each destination by kind and name; the platform checks that every referenced table, dashboard and report exists — in the store its kind names — and that the home page is one of the navigation's own destinations before saving. The app itself holds no data: it is a curated view over the environment's components.

Troubleshooting​

  • "… must be lower snake-case and start with the publisher prefix." — the logical name must begin with {prefix}_ and use only lower-case letters, digits, and underscores.
  • "Entity … is not defined in this environment." — a navigation table does not exist in this environment; create the table first, or remove it from the navigation.
  • "Dashboard … is not defined in this environment." (or Report …) — the navigation names one that has been deleted or was never imported here. Build it, import it, or remove the item.
  • "The home page … must appear in the app's navigation." — choose a home page you have added to the navigation. A home nobody can navigate back to is a screen with no way in once the user has clicked anywhere else.
  • "An app named … already exists in this environment." — choose a different logical name; app logical names are unique within an environment.
  • "You do not have permission to open the dashboard …" (or … run the report …) — the destination exists, but your security role holds no grant on it. An administrator grants <name>.Open for a dashboard or <name>.Run for a report, or the wildcard *.Open / *.Run to cover whatever gets built next.
  • "Form … is not defined on entity …" (or View …) — the app selects a form or view the table no longer has, usually because it was renamed or deleted after the app was built. Open the table's Forms and views dialog and tick the current ones.
  • A form I added to a table does not appear in an app. — that app selects specific forms, so a new one is not included until you add it. The row will say "2 of 5 forms" rather than a plain count. Open the app, select the table's Forms and views button, and either tick the new form or switch the list back to every form of this table.
  • Give an App to the People Who Will Use It.
  • Create an Entity.
  • Create a Form.
  • Create a View.
  • Create a Report.