Skip to main content

Add a Component to a Solution

Goal​

Add a component (such as a table, form, or view) to a solution — either by creating a new one in its designer or by adding an existing one — from the solution explorer.

Prerequisites​

  • You are signed in to the Admin Control Center as a platform administrator.
  • The solution exists and is owned by a publisher (see Create a Solution).

Steps​

  1. Open the Solutions page from the sidebar navigation.
  2. Select Open on the solution's row. The solution explorer shows the solution's components as one tab per type — Tables (8), Apps (2), Reports (1) and so on — and makes this solution your working solution. Each tab name carries how many of that type the solution holds, so you can see the shape of the whole solution without opening anything; selecting a tab lists those components. Only types this solution actually contains get a tab.
  3. To create a new component, use the New menu (for example, New table or New app). This opens the matching designer, where the component you create is added to this working solution.
  4. To add a component that already exists in the environment, use Add existing: choose the component type — Table, Option set, App, Script, Studio screen, Environment variable, Data policy, Report, Saved query, Custom API, Portal, Custom App, Custom Control, Web resource or Role — then pick the component from the list. Every choice is made from a picker; you never type a logical name. Select Add existing.
  5. The component appears under its type's tab, and that tab's count goes up by one. If the solution had none of that type before, the tab appears now.
note

Your selection belongs to the tab you made it in. The commands at the top of the page — Manage components, Dependencies, Remove from solution — act on the component you selected, so switching tabs clears the selection. That is deliberate: a command armed for a component you can no longer see is one you could run by mistake.

note

A report and a saved query are filed under the table they read, beside that table's forms and views. You do not have to say which table: the one you pick already knows, and it is added under it. That is why they appear both here and inside a table's component picker — two ways to the same membership, for the two ways people look for one.

note

A role is not a pointer, so its entry takes you somewhere. A role is in a solution because that solution grants it something — a permission, on a table, for an operation — so choosing Role opens the solution's own Roles page, where that is decided. Adding a row that granted nothing would claim the role travels while the package carried an empty name.

Opening a component​

Select a component's name to open it.

  • A component with a designer of its own — a table, a saved query, a script, a report, a Studio screen, a process, a role — opens in that designer.
  • A component edited in a drawer on its own list page — an option set, an app, a data policy, an environment variable, a Custom API, a portal — opens that list with the component selected and its editor already open, rather than leaving you to find it a second time in a list of thirty.
  • A custom app, custom control or web resource has no editor — it is uploaded, not authored — so it opens its list with the row selected, ready for the commands that act on it.

You can also tick the row's checkbox and choose Open at the top of the page. Both do the same thing. The name is an ordinary link, so you can open it in a new tab as well.

note

Business rules are the exception. A business rule belongs to the form it runs on, and the overview does not know which form that is — so its rows do not open. Reach a business rule through its table's form, using the form designer's Events action.

Choosing which of a table's components to include​

A table is more than one thing: it has fields, forms, views, and relationships. You do not have to include all of them. When you Add existing a table, a component picker opens listing the table's fields, forms, views, and relationships, each with a checkbox. Select the ones this solution should carry and choose Save — the table itself is always included, and only the sub-components you checked travel with it.

You can revisit this choice at any time, even after the table is already in the solution. There are two ways in:

  • Select the table under the Tables tab and choose Manage components.
  • Choose the table again under Add existing — a table already in the solution is still offered there, and picking it reopens its picker rather than adding it twice.

The picker reopens showing what is currently in the solution, so you can add or remove individual fields, forms, views, and relationships whenever you need to — for example, to add a new form you built for an existing table without pulling in everything else, or to take a view back out of the solution.

Each table's row shows how much of it travels in this solution, so a table you added without selecting any of its fields says so plainly rather than looking complete.

note

Columns and relationships travel with their table. A table's definition carries all of its columns and relationships, whichever boxes are checked, so their checkboxes decide what this solution's lists show rather than what the exported file holds. Forms, views and saved queries are different: only the checked ones travel.

Seeing only what the solution contains​

Every list inside a solution shows that solution's components, not the environment's. That is true of the pages in the solution's own navigation — Apps, Tables, Option sets, Environment variables, Saved queries, Scripts, Reports, Studio screens, Custom APIs, Portals, Roles, Data policies, Custom apps, Custom controls and Web resources — and of a table's Fields, Forms and Views lists once you open one. A table you added without picking any fields therefore shows an empty field list. The exported file still carries all of the table's columns (see the note above).

The default ("Main") solution is the exception: it holds everything in the environment, so its lists are never narrowed. That is where to go to see everything an environment has, whoever put it there.

A component you create while a solution is open is added to that solution automatically, so it appears in its list straight away.

If something you use is missing from the list​

A solution carries what it needs. If your app navigates to a screen, or your report names a saved query, that another solution installed, add that component to your solution — with Add existing on the solution overview, or through a table's component picker for a field, form or view. That is how dependencies are declared, and it is what lets the target environment check them when your package is imported.

Note what a narrowed list does not mean: a component missing from this solution's list still exists in the environment and still works. Anything reached by logical name — a screen an app navigates to, a script a rule imports, an option set a field binds to — resolves at run time whichever solution installed it. The list is answering "what does this package carry?", not "what can this app reach?".

Seeing what depends on a component​

Select a component and choose Dependencies. A panel opens with two lists:

  • Needed by — everything in this environment that depends on the component. This is the list to read before deleting anything: if a lookup column points at a table, or an app's navigation opens a view, deleting it would break them, and the platform will refuse.
  • Needs — what the component itself depends on. This is the list that explains why importing it on its own into another environment would fail: whatever is here has to travel with it, or already be there.

Each row says what the other component is, which table it belongs to when it belongs to one, and why it is in the list — "a lookup column points at it", "a column takes its values from it", "a security role grants a permission on it", and so on.

The answer is worked out from the environment's metadata each time you open the panel, so it is never out of date. It is also not limited to this solution: the question is what exists in the environment, whoever installed it.

Dependencies is unavailable for Custom Apps, Custom Controls, Web Resources, processes, Custom APIs and portals. These are not described by the same metadata — nothing reads what a Custom API's script touches, and a portal's links to the screen it publishes and the tables it may read are not modelled — so rather than show you an empty panel that looks like an answer, the command is switched off.

Removing something from a solution​

Select the component and choose Remove from solution. This removes only its membership of this solution — the component itself stays in the environment and in the default ("Main") solution, and no data is destroyed. To take a single form, view, field, or relationship out of a solution, reopen its table's component picker and clear its checkbox.

caution

Remove doesn't check what still needs the component. If a column in this solution takes its values from the choice list you remove, the solution still exports, and its next import into an environment that doesn't have the choice list is refused. Select the component and open Dependencies first: anything under Needed by that is in this solution needs it.

What happens behind the scenes​

Adding an existing component records that it belongs to this solution — a component can belong to more than one unmanaged solution. The component picker records exactly which of a table's sub-components belong to the solution; saving it adds the newly-checked ones and removes the newly-cleared ones, leaving other tables untouched. Removing a component removes only that membership; it does not delete the component itself. The default ("Main") solution is the exception — it always holds every component, so it offers no component picker and nothing can be removed from it.

Troubleshooting​

  • "field '…' references '…', which is neither in the package nor in this environment." — shown when you import. A column in the package looks up a table, or takes its values from a choice list (option set), that the package doesn't carry and the environment doesn't have. Nothing was imported. If another solution brings it, import that solution first. Otherwise, in the environment you exported from, select the table on the solution's overview, choose Dependencies, add what's under Needs with Add existing, and export again. Any publisher's component can be added; its prefix doesn't have to match the solution's.
  • "Component … already exists in the solution." — that component is already referenced by the solution.
  • Create a solution.
  • Create a publisher.