Building apps across organizations

This page is for people who build and ship CYPEX applications. It covers what changes about that job once a deployment has more than one Organization.

Organization scope on this page is enforced by CYPEX itself, not by the browser. Hiding a row in the admin panel would be cosmetic; what is described below holds even for a caller who manipulates the request directly.

The Applications page does not show every application in the deployment to every admin. A system admin can pick any organization in the organization filter, or clear it to see everything. An organization admin is always restricted to their own organization — changing the filter in the browser does not widen what comes back.

Within that scope, an application is listed when two things hold: the application is owned by a role you hold (or has no owner role at all, or you are a CYPEX admin), and the application either belongs to the organization in scope or belongs to no organization. An application with no organization is the mechanism for sharing across tenants — there is no separate “global app” switch, it is simply an app whose organization was never set.

Only applications with a published release appear here. An app that has been generated but never published is absent from the list for everyone.

Info

An admin with no organization is not restricted. An admin account that is not attached to any organization has no organization to be restricted to, and sees every application its roles allow. Check that each organization admin actually has an organization assigned.

The role filter is an exact match, and it narrows within the organization scope rather than widening it. Note that the two filters are linked: choosing a role reduces the organization list to the organizations that role is mapped to, and a selection that stops being valid is cleared for you.

flowchart TD
    A[Open Applications] --> B{system admin?}
    B -->|yes| C[Scope = selected organization<br/>or all organizations if cleared]
    B -->|no| D[Scope = caller's own organization<br/>filter choice cannot widen it]
    C --> E[Keep apps owned by a role the caller holds]
    D --> E
    E --> F[Keep apps in scope<br/>or with no organization set]
    F --> G[Published releases only]
    G --> H[Applications list]

In practice, the same deployment looks different depending on who is looking at it:

Build Apps — system admin

A system admin with no organization filter selected sees every app in the deployment: SMI App (org smi_org_admin) and Eshop App (org eshop_organization). The sidebar shows the full Advanced (System admin) section, including Schema Access.

Build Apps — organization admin (smi_org_admin)

The same list, seen by an organization admin scoped to the smi_org_admin organization: only SMI App is visible. The sidebar still offers Organizations — organization admins can view it — but not Schema Access, which is reserved for system admins.

Build Apps — organization admin (eshop_organization)

A different organization admin, scoped to eshop_organization, sees only Eshop App. Same deployment, same page, different rows — enforced by CYPEX, not by hiding rows in the browser.

Tip

Sidebar label. The sidebar entry is Applications, under Builder. “Build Apps” is the heading on the page itself; both names refer to the same place.

The full mechanics of packaging and restoring an application are on the Export and Import Applications page — read that first for the wizard steps, conflict resolution, and package structure. This section covers only what changes when the caller is an organization admin instead of a system admin.

The export wizard’s first step, Current Application Overview, contains an Export Organizations picker. It offers the organizations you can act on — all of them for a system admin, your own for an organization admin — narrowed to the organizations the application’s role is mapped to, and pre-selects automatically when only one survives or when the app’s own organization is among them. If the role has no organization mappings at all, no narrowing happens and every organization you can reach is offered.

That choice is not merely a client-side filter. On the Objects, Views & Queries step, an organization admin’s query list is recomputed against their own organization no matter what the form requests, so only queries reachable from that organization’s granted schemas are offered. Views belonging to a module that is mapped to no organization are always included — that is the cross-tenant case, and it is a property of the module’s mapping, not of the query itself.

The User Roles & Access Mapping step behaves differently and is worth checking by hand. Its user list is filtered by whether the role is mapped to a selected organization, not by which organization each individual user belongs to. If a role serves more than one organization, the step can offer users outside the organization you are exporting for. Review the selection before completing an export you intend to hand to another team.

The result is visible side by side on the same export wizard step, for the same kind of application, depending only on who is running the export:

Export wizard — Objects, Views & Queries (system admin)

Exporting as a system admin: Queries shows all 12 queries the app's role has access to across every organization it's mapped to.

Export wizard — Objects, Views & Queries (organization admin)

Exporting the same kind of app as an organization admin: Queries drops from 12 to 1 — only the query reachable from the caller's own organization survives.

Warning

An organization-admin export is a partial package by construction. If you export as an organization admin and hand the ZIP to another team, the package will be missing every query and object belonging to organizations you are not scoped to — not a bug, but a consequence of the export never having had access to that data. Run the export as a system admin when you need a complete, cross-organization package.

Import has a matching Organization Mapping section, described on the Export and Import page. It matches each organization in the package against the target deployment’s own organizations by domain, shows how many matched, and lets you redirect the rest. The organization identifiers embedded in the package are never trusted; an unmapped organization stops the import rather than guessing.

The Applications and export scoping above act on top of a more fundamental gate: an organization only has queries to show in the first place for the PostgreSQL schemas it has been granted through Schema Access. If Org B’s export shows a thinner query list than Org A’s, the first thing to check isn’t the export step — it’s which schemas are granted to each organization, via the Setup guide → configure org-scoped application visibility.

Before shipping an app that’s meant to behave differently per organization (or that should behave identically and currently doesn’t), verify it end to end rather than trusting a preview alone:

1. Confirm both organizations have the schemas the app needs. Open Schema Access for Org A and Org B and compare their granted modules/schemas. A difference here is the most common root cause of “the app looks different for Org B” reports.
2. Confirm the role is mapped to both organizations. Follow Setup guide → How to give users access to an organization and check that the role’s Organizations tab lists both Org A and Org B.
3. Know which kind of app you have. An application belongs to exactly one organization, or to none. A no-organization app is a single definition with a single release history, served to every organization — change it once and both organizations see the change. An app assigned to Org A does not serve Org B at all; serving both means either clearing its organization or maintaining a second application. There is no mode where one organization-assigned app definition is shared by two organizations.
4. Log in as an Org A user and as an Org B user (two different sessions — a private/incognito window for the second is the simplest way to hold both at once) and launch the app from each session:
   • Compare which queries and pages render data — a page backed by a query with no rows for that organization will legitimately render empty, not broken.
   • Compare the application list itself: each user should see only their own organization’s apps (screenshots above) plus any shared apps that belong to no organization.
5. Cross-check with an export, following the section above: export as each org’s admin and confirm the Queries step’s count matches what that organization’s role can actually reach. A mismatch usually means a Schema Access or role/organization mapping problem, not an app bug.
6. Or check it without a second login. Access Preview resolves what a role can reach in a given organization — apps, queries, functions, and state transitions — without signing in as that user. Use it to catch a misconfiguration quickly, and the real-session procedure above when you need to confirm what the rendered application does. The Changes Preview inside the app editor shows layout, not organization scope, so it will not surface this class of problem.

Merge Applications, reached from the MERGE button on the Applications page, combines applications built independently for the same role. The merge form has its own Organization picker: the merged result is a new application assigned to the organization you choose there, and it does not inherit the source applications’ organizations. The source applications are left untouched, and merging never changes which organizations a role is mapped to.

Release Management save points and releases, reached from the History and Releases panels in the app editor, are per-role and not per-organization. There is one release history per application, shared by every organization that role serves. Promoting a release affects every organization mapped to that role simultaneously; there is no way to publish a release to Org A only while Org B stays on the previous one.

• Applications — the admin-panel reference for generate / edit / export / delete.
• Export and Import Applications — the full export/import wizard, package structure, and conflict resolution.
• Merge Applications — combining same-role apps built independently.
• Release Management — save points and releases, shared across every organization a role serves.
• Schema Access — granting PostgreSQL schemas to organizations; the upstream gate on which queries an org’s apps can use.
• Setup guide — assigning users and roles to organizations.
• Capabilities vs Data Scope — the Roles vs Organizations mental model this page’s scoping rules build on.
• Access Preview — resolve what a role can reach in a given organization, without a second login.
• Application Designer — building the pages, menus, and layout of the application.
• Governance evidence — where evidence of an organization-boundary decision is recorded.