inflowDocsLearning path

Operate interface-control plugins

Audience: platform administrators and operators. This guide covers interface-control plugin packages, which add browser controls such as a map to the interface designer. It explains how to upload, inspect and remove them, how to configure their external providers and how to move interfaces that use them between servers. For the companion guide to placing and publishing installed controls, see the interface-control author manual. Developers who build packages have separate guides; see Related guides.

Every administrative step here needs platform plugin administration rights. The server checks those rights on every /api/admin/plugins request. If you do not see Authorization → Plugins, ask a platform administrator. Choosing a control in the designer gives an author no extra rights.

Know what you are uploading

Uploading is the trust decision. There is no separate review or approval step. A package that passes every check is active and served the moment the upload finishes, for every kind of package.

An interface-control package contains trusted browser code. Once it is uploaded, its JavaScript runs in people's browsers with their access. It is trusted code, not a sandbox. The plugin runner's isolation protects Java function execution only, not browser code. Upload only packages from a publisher your organization trusts, and check the fingerprint against the one the publisher gave you before you upload (see Upload a package).

Inflow recognises three kinds of package from the manifest:

Kind What it contains How it runs
UI-only Interface controls and their browser files only. No Java class. Inspected and served by the API. The plugin runner never loads it.
Mixed Interface controls and a Java plugin class. The Java half uses the existing plugin runner path; the browser half is served like a UI-only package.
Legacy Java A Java plugin class only, such as an expression-function plugin. Unchanged. See the expression-function runner reference.

Version handling differs by kind:

  • A UI-only package is upgraded in place by uploading its new version: the new version is live at once and the earlier version is kept for publications that already use it.
  • Mixed and legacy Java packages keep one active version. Replacing one means uninstalling it and uploading the new version; uploading a new version over an installed one is refused with "Uninstall it first". Publications that pinned the old version then show their controls as unavailable.

Before you start: operator settings

Operators set these values in the server's configuration. Each one needs a restart to take effect.

Setting Default What it does
plugins.expression-functions.security.strict true Strict archive verification. Keep it true outside explicit development mode.
inflow.environment.key local The name of the environment this server is, for example staging or production. Provider configuration is stored and resolved per environment key. The value must be lowercase: a letter followed by up to 63 letters, digits or hyphens ([a-z][a-z0-9-]{0,63}). Any other value, such as Production, is silently replaced by local.

Set strict verification in conf/custom_config.properties, or in the file named by INFLOW_CONFIG_FILE, as described in Feature switches:

plugins.expression-functions.security.strict=true

There is no global plugin kill switch. The former setting plugins.expression-functions.security.kill-switch was removed. Uploaded plugins serve according to their own state only: installed and enabled serves, disabled or uninstalled does not. If an upgraded server's configuration file, JVM properties or environment still name the old key, with any value, the server starts normally, ignores it and logs one line at startup:

retiredSettingIgnored key=plugins.expression-functions.security.kill-switch reason=REMOVED_BY_OWNER_DECISION ...

The same applies to any spelling of the key in JVM properties or the environment (for example PLUGINS_EXPRESSIONFUNCTIONS_SECURITY_KILLSWITCH) and to scoped forms such as feature-flags.global.plugins.expression-functions.security.kill-switch, with any value: the server starts, ignores them and logs the one line above. You can delete the line from the configuration at any time; nothing else changes.

Set inflow.environment.key as an ordinary server property. For example, in the API container's environment:

environment:
  INFLOW_ENVIRONMENT_KEY: staging

Use one stable key for each environment. Provider configuration saved under one key does not apply under another, so renaming the key leaves every provider unconfigured until you configure it again. After a restart, open Providers on any package that declares providers and check that the subtitle names the environment you intended. A subtitle that says local on a non-local server means the key was missing or invalid.

Emergency stop. To stop a plugin, use Disable on its row (it can be enabled again) or Uninstall (it is removed). Neither needs a restart, and both are recorded in the audit log (Disable as a state change, Uninstall as PLUGIN_UNLOADED). Disabling a plugin stops every version of it: its control catalogs come back empty and no control asset or provider setting is served on any API node as soon as the change commits. Its Java functions and process steps stop at commit on the node that made the change, and on each other API node at that node's next reconciliation, by default within 5 seconds (plugins.expression-functions.reconcile-delay-ms). Stored provider settings and installation records are kept on disable. Published forms keep their settings and show the controls as unavailable. Pages already open in browsers withdraw the controls at their next catalog check; see How fast withdrawal reaches open pages. To stop every uploaded plugin, disable each one. Bundled Inflow function packs are part of the platform and are not stopped this way.

What you should see: on Authorization → Plugins, each plugin shows its own state (Active, Disabled or Not active). There is no server-wide "paused" notice. If the plugin runner is monitored on this node, the page also shows the Plugin runner healthy badge. UI-only packages do not need the runner. Mixed and legacy Java packages do.

Upload a package

  1. Before you upload, compute the SHA-256 of the archive on your own machine (sha256sum file.zip, or Get-FileHash file.zip in PowerShell) and compare it with the fingerprint the publisher gave you through a separate channel. Uploading is the trust decision; there is no later review step.
  2. Open Authorization → Plugins.
  3. Drop the .zip or .jar archive on Upload a plugin, or choose Choose file and select it. The file must be 5 MB or smaller.
  4. Wait while the drop area reads "Checking the package and making it live…". Inflow checks the archive limits, the digest, size and type of every declared file, refuses undeclared or linked files, checks the manifest, control contract, host and SDK versions, and inspects any Java code in the isolated plugin runner. Interface-control (browser) files are checked statically and never run during the check. Java inspection is not static: the runner loads the package and runs its lifecycle and metadata code (Plugin.start(), extension constructors, getDescriptor()) inside the isolated runner to list its functions, so that code runs even for a package that is then refused.

What you should see:

  • The line "file was uploaded and is now active."
  • A row for the plugin with the badges Active and its kind (UI-only, Mixed or Java), "By publisher · Version x · Uploaded by you, date", and Fingerprint prefix...suffix with a Copy button. Compare the fingerprint once more with the publisher's.
  • The actions Details, Providers (only when the package declares providers), History (only when you may read the audit trail), Disable and Uninstall.
  • Authors with edit rights on an interface find the controls under Installed controls in the designer Toolbox at once; a Java or mixed package's functions are in the expression catalog.
  • The audit log holds one PLUGIN_UPLOADED event with you as the actor, the plugin id, version and SHA-256, the transition ABSENT → STARTED and activation=UPLOAD.

A file that fails any check is refused with its code (see Troubleshooting), and nothing is stored or served. A package that declares neither functions nor controls, or whose function names collide with another plugin's, is refused too.

Details opens a read-only view of what an installed plugin contains: publisher, version, kind, archive name, the full platform fingerprint, who uploaded it and when, its interface controls, each external provider (purpose, Connects to origins, Receives data categories and Needs, marked Visible in the browser or Secret, stays on the server) and its functions. Use it to check what a plugin does; it changes nothing.

Packages left pending by an earlier version

A server upgraded from a version that had approvals may still hold packages that were uploaded but never approved. Inflow does not turn them on by itself, on upgrade or at restart. Their row shows Not active with "Uploaded before uploads went live. Nothing of it is served. Enable turns it on after the same checks as an upload."

  • To use one, check its Details and fingerprint, then choose Enable. Inflow runs the same activation checks as an upload and records PLUGIN_STATE_CHANGED (PENDING → STARTED) with you as the actor. The line "plugin-id is now active." confirms it.
  • To get rid of one, choose Uninstall.
  • Its Providers stay unavailable ("Enable this plugin before configuring its providers.") until it is enabled.

The former route POST /api/admin/plugins/{id}/approve is kept for existing API callers and does the same as Enable.

Configure external providers for this environment

Uploading a package does not switch any provider on. Each provider stays Off until an administrator saves its required settings on each server; saving the settings turns it on (there is no separate "allow" switch). While a provider is off, Inflow gives published controls neither its configuration nor its admission, and the package code is expected to show its offline alternative instead of calling the provider. This is a contract the trusted code must respect, not network enforcement. Inflow does not intercept browser requests, so neither Off nor "This package calls no external service." proves that a package makes no external requests. That assurance comes from trusting the publisher and checking the package's Details.

  1. Choose Providers on the plugin's row. The dialog subtitle names the environment, for example "External services map-controls calls, in the staging environment." Check that this is the environment key you expect.

  2. For each provider, read its purpose, Connects to, Receives and its badge: Off, Needs settings (turned on, but a required value is missing, so nothing is delivered) or On.

  3. Fill in the configuration fields. Each field is labelled with the name the package declares, for example "Maps JavaScript API key (restricted)". The hint under the field tells you its classification:

    • A browser-public field has the hint "Visible in people's browsers." Enter plain text of at most 512 characters, for example a browser API key or a map ID. A package declares only that the value reaches people's browsers, not whether it is a key, so the advice about keys is shown once above the fields of a provider that has any browser-public field: "Anyone who opens a published control can read these values. Restrict any API key among them to this site." Restrict a browser API key to this site's address with the service that issued it (for Google Maps, a referrer-restricted key). A value that is not a key, such as a map ID, needs no restriction (SCRUM-5089).
    • A server-secret field has the hint "Enter a vault: reference. The secret stays on the server." Never enter the secret itself. Enter only the reference that Inflow's credential vault issued when the credential was stored, which has the form vault: followed by a UUID, for example vault:3f6c2a9e-8b1d-4c57-9e2a-5d0b7f41c8a3. Get the actual reference from the owner of that credential. Once a reference is stored, the field shows "A vault reference is set. Enter a new vault: reference to replace it." Inflow never shows a stored reference back.

    Inflow checks only that a server-secret value looks like a vault reference. It does not check that the credential exists or works. So On does not prove that a secret is usable.

  4. Read the callout "Saving turns this provider on": once its required settings are saved, published controls in this environment load the provider in people's browsers and send it the data the package declares.

  5. Choose Save and turn on (on a provider that is already on, the button reads Save).

What you should see: the badge reads On once every required value is saved. It reads Needs settings if a required value is still empty; nothing is delivered until you complete it.

What reaches browsers

  • Only the published runtime receives provider settings, and only for providers that are on and complete in this server's environment. The runtime receives the browser-public values and the list of providers that are on.
  • The designer, design preview and the author catalog never receive provider configuration or admission. Cooperating packages therefore stay provider-free while authoring; as above, Inflow withholds the settings but does not block the browser's network.
  • Server-secret references never leave the server. They are not in packages, interface JSON, releases, logs, the audit trail or any browser response.
  • A browser-public value is public by definition: anyone who can open the published form can read it. Restrict every browser key at the provider, by allowed website referrers and by allowed APIs, before you enter it here.

Turn a provider off

Choose Turn off on the provider in Providers. From then on the server delivers no configuration or admission for that provider. Turning off changes only that: the server keeps whatever values are stored at that moment (a vault reference stays set), even if another administrator saved new values after you opened the dialog. API callers send PUT …/providers/{key} with {"authorized": false}; any values sent with it are ignored. so choosing Save and turn on later turns it on again without re-entering them. To remove the values as well, clear the fields, choose Save and turn on (the provider then shows Needs settings and delivers nothing) and then Turn off, or uninstall the plugin. Open published forms pick up the change at their next catalog check, then dispose of the control and mount it again without the provider. A cooperating map control falls back to its offline alternative.

Illustration, not verified evidence for this manual. In a lead-run journey on 2026-11-11, a Google Maps sample control showed "Offline map: not Google Maps — Google Maps is not enabled for this environment." with the provider off. That sample (T029) is not in this repository yet and no evidence receipt is linked here, so treat the text as an example of a package's own offline message, not as a guaranteed Inflow message.

Revoking cannot undo anything that already happened in a browser. Code already running, data already sent to the provider and a browser key already delivered stay out of Inflow's control. If you suspect misuse, also revoke or rotate the key at the provider and follow your normal incident process.

How fast withdrawal reaches open pages

  • Lifecycle changes of one plugin never overlap. Upload, upgrade, enable, disable and uninstall of the same plugin id wait for each other across every API node until the earlier change commits or rolls back, and each then acts on the installation that is current in the database. A disable that waited for an upload disables the new version; a change whose plugin was removed meanwhile is refused ("The plugin changed on the server while this was being done. Reload and try again.").

  • Uploaded Java functions and process steps appear at commit. Until the upload (or enable) has committed with its audit record, its functions are not listed, not accepted by expression validation and refuse every call, and its process-node step is not on the palette and is never dispatched. A rolled-back change never exposes them.

  • Disabling or uninstalling a plugin takes effect for controls on every API node as soon as it is committed, because each catalog and asset request checks the shared installation state. Catalogs no longer list the plugin's controls, and its assets are refused. Its Java functions and process steps stop at commit on the node that made the change; other API nodes withdraw them at their next durable-state reconciliation, by default within 5 seconds (plugins.expression-functions.reconcile-delay-ms).

  • Turning a provider off leaves the control available. Catalogs still list it and its assets are still served, but the catalog carries neither that provider's settings nor its admission. A cooperating control then shows its offline alternative.

  • Open pages check their control catalog every 15 seconds. A check that has no answer after 10 seconds withdraws the controls. When a check shows a control or its provider settings have changed, the page disposes of the control and calls the package's own cleanup. Browsers may delay checks in background tabs.

  • Disposal is cooperative. It aborts work the host registered and runs the package's cleanup code. It cannot recall downloaded code or completed external calls.

When the declaration changes

Provider settings are tied to the exact reviewed declaration: purpose, origins, data categories and configuration needs. If an upgrade changes any of these, the dialog shows Declaration changed, and the provider is unconfigured and offline. Its stored values and permission are suspended, not deleted: they never apply to a different declaration, but they apply again automatically if a later version brings back exactly the declaration they were saved for. If you want a provider to stay off whatever happens, choose Turn off. Do not rely on a declaration change to switch it off. A save made against an out-of-date view is refused with PLUGIN_PROVIDER_DECLARATION_CHANGED ("This provider's reviewed declaration changed. Review it again before saving."). The dialog then reloads so that you can review the new declaration.

Google Maps and similar providers

Every deployment includes Inflow's own Google Maps control, the plugin inflow-google-maps (see Inflow plugins). Its provider google-maps is off on a new server. The steps below turn it on, using that plugin's Providers.

Inflow does not create Google accounts, keys or map IDs. The organization's Google Cloud owner prepares them with Google's own instructions, which change over time. Check these Google pages when you do the setup:

Then follow these steps:

  1. In the organization's Google Cloud project, make sure billing is set up and the Maps JavaScript API is enabled. Google refuses map loads otherwise.
  2. Create a browser key just for this environment. Restrict it to the website addresses people use to open published forms on this server, and to the Maps JavaScript API only. Do not reuse a server key or an unrestricted key.
  3. If the package's review lists a Map ID need, create a map ID in the same project.
  4. Compare the package's Connects to origins (for example https://maps.googleapis.com and https://maps.gstatic.com) and Receives categories with what your privacy owner approved. Make sure published forms meet Google's attribution and terms requirements. Do not hide the map's attribution.
  5. In Providers, enter the key and the map ID as browser-public values. Keep any server-side token in the vault and enter only its vault: reference. Choose Save and turn on.
  6. Sign in as an ordinary runtime user and open a published form that uses the control. Check that the real map appears, and use the browser's developer tools to confirm that requests go only to the reviewed origins.

On means only that Inflow has the required values and that you saved them. It does not check the key, billing or connectivity. If the map still fails after Inflow delivers the configuration, the failure is between the browser and the provider; see Troubleshooting. Local development stays provider-free unless you deliberately save a provider's settings.

A real Google Maps load with an operator-provided key is qualified separately (T029). Behaviour shown with stubbed providers is not evidence of a working Google configuration.

Audit

Each save and each Turn off records a PLUGIN_PROVIDER_CONFIGURATION_CHANGED event against the plugin. The event holds the plugin, provider and environment, the names of the configuration keys that changed, and whether the provider was on before and after (previousAuthorized, authorized). It never records a value or a vault reference.

Inflow plugins (Google Maps)

Some plugins are part of Inflow itself. The Google Maps control (inflow-google-maps, publisher Inflow.ai) is one of them: every deployment has it, installed and enabled, with no upload. Its row in Authorization → Plugins carries an Inflow plugin badge and the note "Included with Inflow. It is always on and is updated with Inflow."

  • What you can do: open Details to review its controls, provider, origins and data, and open Providers to enter a browser key and turn the Google provider on or off for this environment (see Google Maps and similar providers).
  • What you cannot do: Disable, Enable, Uninstall, Versions and History are not offered. The server also refuses them (PLUGIN_MANAGED_BY_INFLOW), and a package upload with the identifier inflow-google-maps is refused (PLUGIN_ID_RESERVED_BY_INFLOW). To keep real maps away from people, turn its provider off. The control then shows its offline map. To keep the control out of an interface, the interface's author removes it.
  • Integrity: at every start and reconciliation, each server restores the plugin from the application's own bytes. It runs the same archive, fingerprint, manifest, contract, asset-digest and default checks as an upload, and runs no plugin code on the server. A copy on disk that differs is replaced. A build whose bundled package fails a check does not start, and its log names the plugin.
  • Upgrades: a later Inflow release can carry a newer version. It becomes current on its own, and new designs use it. An interface moves to it only when its author uses Upgrade to … on the control in the designer and republishes (see Upgrade to a newer control version). Interfaces published with an earlier version keep loading that exact version, which the release still carries, until they are republished. Provider settings carry over while the provider declaration is unchanged. If it changed, the provider goes back to off and Declaration changed asks you to review it again.
  • Version 2.0.0 (SCRUM-5150): the release that carries 2.0.0 makes it current and keeps 1.0.0 for interfaces published with it. 2.0.0's provider declaration adds the host https://places.googleapis.com (address search), so after the upgrade Providers shows Declaration changed and the provider is off. Until you review it and choose Save and turn on again, every form shows the offline map, including forms still on 1.0.0. Enable the Places API (New) and the Geocoding API on the key for address search, picked addresses and placing records by address. With only the Maps JavaScript API enabled, the map works and those features show Google's refusal.
  • Barcode and QR (SCRUM-5160): the Barcode and QR control (inflow-barcode, publisher Inflow.ai) is an Inflow plugin too, in every deployment, with the same rules: no Disable, Uninstall or upload over its identifier (PLUGIN_ID_RESERVED_BY_INFLOW), restored from the application's own bytes at every start, and upgraded with Inflow. It declares no provider, so its row offers only Details: it reads codes from the camera, a handheld scanner or typing, and draws codes, entirely in the person's browser, and sends nothing anywhere.
  • The sample is separate: the developer kit's Google Maps sample is the plugin service-visit-maps by "Example Org". If someone uploaded it on this server, it stays an ordinary uploaded plugin, with its own versions, providers and published interfaces. Both controls are offered, under different names.

Give developers the certified samples (developer kit)

Authorization → Plugins has a Developer kit section for platform administrators (the same people who administer plugins; nobody else sees it). It lists the sample projects this Inflow build carries: the UI-only starter, the mixed UI and Java sample, and the Google Maps sample when the build includes it. Each row shows the sample's name, version and full SHA-256, a Copy button for the SHA-256, and Download.

Where the certified versions are recorded: the committed kit (examples/interface-controls/developer-kit/manifest.json) and examples/interface-controls/developer-kit.receipts.json at the deployed commit name every sample's version and SHA-256; every platform build serves exactly those (SCRUM-5212). This says what that source certifies; it does not prove which commit a particular deployed Studio was built from, or that the Google provider is enabled. At runtime, inspect the Developer kit row and compare its version and SHA-256 with the file before handing the archive to a developer. If the row is absent, have the platform build owner check the exact deployed build and its kit certification rather than modifying a certified sample in place.

  • The download is the exact ZIP the release check certified. Compare the SHA-256 of the saved file with the one shown (sha256sum file.zip, or Get-FileHash file.zip in PowerShell) before handing it to a developer.
  • Every download is recorded in the audit log as PLUGIN_DEVELOPER_KIT_DOWNLOADED with the sample, version and SHA-256 (never the content).
  • Since SCRUM-5212 the certified kit is committed in the repository (examples/interface-controls/developer-kit/), and every platform build includes it. A build whose committed kit is missing or no longer certified fails, naming why, so a normally built environment always lists the samples.
  • Not included in this build therefore means that this deployment was built outside the platform build, or from an older Inflow version. Have the platform build owner check the exact deployed build.
  • When a sample, or a tool it is certified with, changes, the build engineer runs the developer-kit step and commits what it writes: the kit folder, the receipts and the release history (see the README, "Building Distributable Artifacts"). A sample whose files changed gets a new patch version before it is certified again: a server that already has a version refuses different bytes under that version, and the developer-kit step refuses to certify them.
  • Automation: each download button has data-agent-id="admin.plugin.developer-kit.<sample>.download" and the same command id. The API is GET /api/admin/plugins/developer-kit and GET /api/admin/plugins/developer-kit/<sample>/download?sha256=<the listed SHA-256> (409 if the server now holds a different build of the sample: list again).
  • A sample named as failing the integrity check is not offered; have the platform build owner rebuild this server from the repository.

Disable, enable and uninstall

Disable

  1. Choose Disable on an active row.
  2. For a package with interface controls, the Disable interface controls dialog lists where the plugin is used. For example: "2 published interface version(s) and 1 draft(s) use its controls." Each version is listed as current version, kept for earlier publications or no longer available, with the interfaces that use it. Disable stays blocked with "Where this plugin is used must be shown first." until the list has loaded.
  3. Read "Its controls stop loading everywhere at once, in every version. Settings are kept and the plugin can be enabled again." Then choose Disable.

What you should see: the banner "plugin-id was disabled." and the State Disabled. Published forms show "Control not available — This control cannot be shown right now. Its settings are kept." Authors no longer see the controls in the Toolbox. New requests are refused on every API node, not only the one you used. Pages already open withdraw the controls at their next catalog check (see How fast withdrawal reaches open pages). Choose Enable to bring the plugin back ("plugin-id was enabled.").

Uninstall

  1. Choose Uninstall on the row. The Permanently uninstall plugin dialog shows the same usage list for an interface-control package.
  2. Type the plugin id where asked ("Type "plugin-id" to permanently uninstall"), then choose Uninstall permanently.

What you should see: "plugin-id was permanently uninstalled. The lifecycle event was recorded in the audit log."

Uninstalling has these effects:

  • The current artifact is removed. Published forms show Control not available, and drafts keep their settings.
  • The plugin's provider configuration is deleted in every environment.
  • Former UI-only versions kept for publications are not destroyed, but nothing serves them while the plugin is absent.
  • Audit history remains.

History

Choose History to list lifecycle events, newest first, with when, event, details, version, state change, fingerprint and who. History is shown only to administrators who may read the platform audit trail. Every plugin event kind has its own label (SCRUM-5078):

Event Details shown
Uploaded and turned on (PLUGIN_UPLOADED; Uploaded for review for an upload an earlier version left pending) —
Approved and enabled (PLUGIN_APPROVED, earlier versions only), Enabled, Disabled (PLUGIN_STATE_CHANGED), Uninstalled (PLUGIN_UNLOADED) —
Upgraded (PLUGIN_UPGRADED) "vold → vnew. The earlier version is kept for its publications."
Upgrade staged (earlier version) (PLUGIN_UPGRADE_STAGED) "vx staged."
Kept version released (PLUGIN_RETAINED_VERSION_RELEASED) "vx is no longer kept."
Kept version revoked (PLUGIN_RETAINED_VERSION_REVOKED) "vx revoked. n pinned publications (interface vn, …) now show "Control not available"."
Provider turned on, Provider turned off, Provider settings saved (PLUGIN_PROVIDER_CONFIGURATION_CHANGED) "Provider key in environment. Settings changed: setting names."

Only identifiers are shown: provider and environment keys and the names of the settings that changed, never a value, vault reference or key. Any other event type reads Lifecycle event; its exact type is in the audit log.

Upgrade a UI-only package and keep earlier versions

Upgrading never changes a published interface. Each publication keeps the exact version it was published with: plugin, control, contract version, plugin version and artifact SHA-256. Since SCRUM-5091 an upgrade, like a first upload, goes live on upload: there is no staging or approval step.

  1. Compare the SHA-256 of the new archive with the publisher's, as for a first upload. Validating the exact file with the control tools (inflow-control validate <archive>.zip, see the control tools README) is a structural check only.

  2. Read the new archive's root plugin.json and compare its interfaceControls.controls, providers (each provider's purpose, origins, dataCategories and configuration classifications) and assets with the version installed now (its Details). Any provider whose declaration changed is off after the upgrade until you save its settings again under Providers; its earlier settings are suspended, not deleted (see When the declaration changes). Kept earlier versions are served with the provider declarations and settings of the package that is current, so an upgrade that changes a provider affects publications on kept versions too.

  3. On Authorization → Plugins, choose Versions on the plugin's row (SCRUM-5079; shown only to plugin administrators, and only for an installed UI-only control plugin). The dialog shows the Live version with how many publications and drafts use it, the Kept versions with the publications that pin each, and any Versions no longer available that publications still pin.

    1. Under New version, choose the archive (or drop it on the area).
    2. Make a new version live opens. It names the file and the version that stays kept, and lists where the plugin is used now, per version. Upload and make live is available only once that list has loaded.
    3. Confirm. "file is now the live version of plugin. The earlier version is kept for its publications." The list refreshes. Cancel uploads nothing.

    Uploading the archive in the page's Upload a plugin area does the same upgrade without showing the usage first. Inflow reads the plugin id from the archive: when a UI-only plugin with that id is installed, the upload is an upgrade. The same checks run (archive limits, digests, manifest and contract, UI-only, a new version number), then in one step the current version is kept for its publications and the new version becomes current and active. An upload always goes live: a plugin that was disabled is enabled again with the new version (a disable or uninstall committed at the same moment is serialized with it; an uninstall makes the upgrade fail with PLUGIN_UPGRADE_STALE). If any check fails, nothing changes.

Mixed and Java plugins keep one active version. Uploading a new version of an installed Mixed or Java plugin is refused with PLUGIN_ID_ALREADY_INSTALLED ("… A Mixed or Java plugin keeps one active version: Uninstall it first, then upload the new version."). Check the usage list, uninstall, and upload the new version.

API callers can upload to POST /api/admin/plugins/{id}/upgrade (multipart form data, the archive in the field file, with the CSRF token in X-XSRF-TOKEN when signed in with a cookie). It answers 202 with {"id", "sha256", "state": "STARTED"}. The former apply route POST /api/admin/plugins/{id}/upgrade/approve is deprecated: it applies a candidate staged by an earlier Inflow version and is a no-op (204) when the SHA-256 it names is already current.

What you should see:

  • The row shows the new version and fingerprint; "file was uploaded and is now active."
  • New designs get only the new version.
  • Existing publications still load their recorded version.
  • In the designer, a node that uses the earlier version shows "Version x of this control is available". The author chooses Review upgrade, and the server checks the whole draft before allowing Upgrade to x. Publishing the upgraded draft is a separate step.
  • The audit holds one PLUGIN_UPGRADED event with you as the actor: the new version and SHA-256, previousVersion and previousChecksum, and activation=UPLOAD.

Upgrade refusals:

Code Meaning
PLUGIN_ID_ALREADY_INSTALLED The installed plugin is Mixed or Java: uninstall it first, then upload the new version.
PLUGIN_UPGRADE_NOT_UI_ONLY Either the installed UI-only package is still not active (left pending by an earlier version: enable it first, then upgrade), or the new archive carries server code.
PLUGIN_UPGRADE_VERSION_EXISTS "This version is already installed or kept for earlier publications. Publish a new version." Also for the same version with different bytes.
PLUGIN_UPGRADE_STALE "The plugin changed while it was being upgraded. Reload and try again." The current version was revoked or replaced meanwhile, for example by an uninstall or another upgrade. A concurrent disable does not cause this: the upload still goes live.

First-release packages declare no configuration migrations. An author's settings are kept as they are and checked against the new version. Settings and event actions that the new version no longer declares are listed, and they block the upgrade of that node.

Send administration API requests (optional)

Everything in this guide is available in Studio. Use the API only for automation.

The administration API uses the same sign-in and request protection as Studio. Changing requests (POST, PUT and DELETE) sent with a sign-in cookie must also carry a CSRF token, or they are refused with 403. The simplest supported way is to send them from the signed-in Studio tab's developer tools console (sign in normally; do not use a development proxy header):

await fetch('/api/public/auth/csrf', { credentials: 'include' });
const xsrf = decodeURIComponent(document.cookie.split('; ').find((c) => c.startsWith('XSRF-TOKEN=')).slice(11));
// Example: release a kept version that no publication uses any more (Studio: Versions → Release).
const answer = await fetch('/api/admin/plugins/map-controls/retained/<sha256>', {
  method: 'DELETE', credentials: 'include', headers: { 'X-XSRF-TOKEN': xsrf },
});

To upload through the API, send the archive as multipart form data in a field named file (const form = new FormData(); form.append('file', fileFromAnInput);) with method: 'POST', body: form and the same header. Every request is still checked for plugin administration rights. Do not paste session cookies or tokens into tickets or chat.

Roll back, release and revoke kept versions

  • Rolling back an interface to an earlier published version that pinned a kept plugin version is allowed. This is an interface author's action, not a plugin-administration one: it needs authoring rights and manage rights on that interface.

    1. Open the interface in the designer and open Version history.
    2. Choose Make live on the earlier version.
    3. Read "Version n becomes what people get. It is published again as a new version; every older version stays in history, and your working draft is not changed." Then confirm with Make version n live.

    The earlier document is published again as a new version that keeps its recorded control pin, and the kept plugin version is served for it. API callers use POST /api/screens/{screenKey}/versions/{version}/rollback, and reuse the same Idempotency-Key header when they retry.

  • There is no operation that makes a kept version current again: the upgrade route refuses a version that is already kept (PLUGIN_UPGRADE_VERSION_EXISTS). To fix a faulty current version, publish and upgrade to a new version number. Re-uploading an old version after an uninstall is technically possible, but it removes the current version from every publication that uses it, so treat it as an owner decision, not as a rollback.

  • Disable and uninstall apply to all versions of a plugin together.

  • To see where each version is used, open Versions (API: GET /api/admin/plugins/{id}/interface-control-impact, which lists each version's role CURRENT, RETAINED or NOT_AVAILABLE, the published interface versions and drafts that use it, and totals).

  • Release a kept version that nothing publishes any more: in Versions, a kept version marked Not used has Release. Confirm "Release kept version x". Its stored files are removed from this server. API: DELETE /api/admin/plugins/{id}/retained/{sha256}, refused with PLUGIN_RETAINED_IN_USE ("n published interface version(s) still use this version. It stays kept for them.") while any publication records it, and with PLUGIN_RETAINED_NOT_FOUND for an unknown version. Audited as PLUGIN_RETAINED_VERSION_RELEASED. Inflow never releases a kept version on its own.

  • Revoke a kept version that publications still pin (SCRUM-5083), for example a version with a defect you must stop serving now. Only that one version is withdrawn; the live version and other kept versions keep working. In Versions, a kept version marked Pinned by n publications has Revoke:

    1. "Revoke kept version x" lists every publication that uses it (interface key and version) and explains the result.
    2. Type the version number to confirm, then choose Revoke version.
    3. Those publications keep their settings. Where they place this plugin's controls, people now see the neutral Control not available ("This control cannot be shown right now. Its settings are kept."). The version moves to Versions no longer available with its publications.
    4. To restore the control, the interface authors open each listed interface, upgrade the control node to the live version (Review upgrade) and publish again.

    Revocation cannot be undone from Studio. The stored files go exactly as for a release; re-uploading those exact bytes is possible only as an upgrade, which makes them the live version. If publications started or stopped using the version after you opened the dialog, the server refuses with PLUGIN_RETAINED_IMPACT_CHANGED ("Where this version is used changed. Review it again before revoking.") and nothing changes; the list reloads. API: POST /api/admin/plugins/{id}/retained/{sha256}/revoke with {"pinnedPublications": n}, where n is the number of publications you reviewed (400 PLUGIN_REVOKE_CONFIRMATION_REQUIRED without it). Audited once as PLUGIN_RETAINED_VERSION_REVOKED with you as the actor, the version and SHA-256, RETAINED → REVOKED, pinnedPublications and up to 20 pinnedInterfaces. Every API node stops serving the version as soon as the revoke commits: before serving a kept version, each node checks that it is still recorded, so no node serves its catalog or code and no publication or rollback can pin it again. A release takes effect on every node the same way. If that record cannot be read, no kept version is served until it can (the live version is unaffected).

Move interfaces between environments

A release of an interface that uses installed controls carries exact pins only: plugin id, control key, contract version, plugin version and artifact SHA-256. It never carries the plugin archive, its installation record, provider configuration, vault references or grants. A value that an interface author typed as a literal control property, for example a browser map key, is part of the interface design and does travel with it (SCRUM-5123). Use provider configuration for keys instead. The designer warns under such a property, and a release review names it under its control (names only, never values; not a blocker). A property counts when the package declares a provider setting with the same key. For the general release and import procedure, see Workspace deployment.

Before importing on the receiving server:

  1. Review the release first (step 5) to see each pin's status on this server. Skip installation for every pin that is already Available here.
  2. For a missing pin, obtain the same artifact the source server runs, and compare its SHA-256 with the pin.
  3. If the plugin is not installed here, upload the artifact through Authorization → Plugins; it is live as soon as the upload succeeds. The receiving server computes its own fingerprint and keeps its own installation record. If the pin is a newer version of a UI-only plugin that is already installed here, uploading it upgrades that plugin (see Upgrade a UI-only package); for a Mixed or Java plugin, uninstall first. A pinned version is accepted when it is installed here as the current version or as a kept version. There is no operation that installs an artifact only as a kept version. If this server already runs a newer version and never had the pinned older one, the only way to keep it is to pass through it as the current version. The upgrade route does not compare version numbers, so it would accept the older version, keeping the newer one. A further upgrade to the newer artifact is then refused while that version is kept. If no published interface version pins the newer artifact, an administrator can review its impact, release the kept version explicitly, and then upload those exact bytes again; otherwise a third, distinct version is needed. While the older version is current, every new design gets it, and any provider declaration changes apply. Treat this as an owner decision. The usual alternative is to ask the release owner to rebuild the interface on the source server against the version this server has.
  4. Configure providers in the receiving server's environment (saving turns them on). The source server's provider settings never travel. The review in step 5 shows each provider's state in this environment, so you can do this step before or after the import.
  5. Review the release. The Interface controls section shows each pin as Available here or Not available here, with its reason:
Status Reason shown
AVAILABLE This exact plugin version is installed and enabled here. A version uploaded here is available as soon as the upload succeeds.
ARTIFACT_MISSING This exact plugin version is not installed on this server.
NOT_APPROVED "This plugin version is on this server but not active. A plugin administrator can turn it on." New uploads never produce it; it remains for a package left pending by an earlier version (choose Enable) and for an upgrade candidate staged by an earlier Inflow version and never applied.
CONTROL_MISSING The installed plugin version does not include this control.
CONTRACT_MISMATCH The installed control uses a different control contract version.
DISABLED The exact plugin artifact is installed here, but this server is not serving its controls. A plugin administrator can check the plugin's own enabled state.
UNAVAILABLE Shown to reviewers without plugin rights: "This control is not available on this server. A plugin administrator of this server can see why."

Providers in this environment. For plugin administrators, every control that is Available here also lists each provider its installed package declares, with the provider's state in this server's environment (inflow.environment.key). The review shows only the provider's name and state, never a setting, browser key or vault reference:

Provider state Shown as Meaning
READY Configured and on Its settings are complete for this environment and it is turned on.
NEEDS_SETTINGS Needs settings A required setting is missing for this environment, or the package changed since it was configured (the settings no longer apply).
OFF Off Its settings are complete, but it is turned off in this environment.

A provider that is not ready is a warning, not a blocker. It does not change the control's status and does not stop the import. Until a plugin administrator configures the provider and turns it on (Authorization → Plugins → Providers), the control uses its offline alternative. The section then says, for example, "1 provider is not ready in this environment … This does not block the import." Reviewers without plugin rights see no provider rows. Provider configuration is plugin administration state, so they see only whether each control is available. A deployment comparison over a trusted link never reports provider readiness: check it in the receiving server's own release review.

What you should see: when every pin is available, "This server serves every control the release pins." If any pin is unavailable, the import is refused (DEPLOYMENT_RELEASE_INCOMPATIBLE), and nothing is written. Rebuilding the release on the source server does not fix a missing control on the receiving server. Upload the artifact there.

Current limitation: interfaces are governed items. The package-import screen does not apply them directly; they arrive only through a governed deployment, which may not be offered on this server (DEPLOYMENT_RELEASE_NEEDS_GOVERNED_DEPLOYMENT). A clean Interface controls check proves only that the dependencies are ready. If governed deployment is not available, record the release as pending, as described in Workspace deployment.

Asset delivery and security posture

Control files are served only from the installed archive, by exact plugin id, SHA-256 and declared path. Each read checks the bytes against the declared digest again.

  • Author route. /api/screens/{screenKey}/interface-controls/assets/... requires authoring rights on that interface and serves only the current version.
  • Published route. /api/screens/{screenKey}/versions/{version}/interface-controls/... requires runtime view rights on that published version. It serves only the pins that the publication recorded, including kept versions.
  • Who may use a published control. Anyone who may open the published interface may see and work with the controls placed on it. No separate grant per control exists. This includes people who open an App Shell application's pages only through the application's own runtime access (SCRUM-5081). Each catalog, asset and record-choice request is checked again on the server under that person's own right to open that exact published version. The data behind a control keeps its own checks: record choices need the person's own data-model view right, an expression property or expression choice list is evaluated on the server only for that placed control and calls rules as that person, and an event runs only the interface's ordinary actions.
  • Rules called from control expressions (App Shell access review). For people who open an App Shell application only through its reviewed access, a rule that an installed control's expression calls runs only when the application's access review granted it (SCRUM-5086). The review (Studio Application access, or POST /api/workspaces/{workspace}/application-runtime-access/previews) lists each such rule as RULE_DEFINITION_EXECUTE on the rule, next to what the rule itself needs (for example DATA_MODEL_VIEW on the model a query reads, or the integration and connector an integration rule calls). Integration, AI task and record rules are marked in the review and in the preview's ruleEffects: they call an external system, call an AI model or write records, and run whenever the page renders or a value changes. Read these before you apply. The rule runs as the person, through the same runtime as a Call a rule action; nothing runs with the publisher's rights. The review records the rule version it saw: when the rule is published again or the interface calls another version, application users are refused (the rule is not run) until you review and apply the access again; that review shows "version changed from N to M" for the rule (preview ruleVersionChanges), and every rule row shows the version it grants (preview ruleVersions). The server enforces the reviewed versions for every rule an application user runs, including Call a rule actions, rule data sources, direct execute-internal requests and rules called by other rules; it checks the group's current reviewed access again just before the rule runs. After you publish a new version of a rule that an application uses, review and apply that application's access again. A rule key or version that the author computed instead of writing it literally blocks the review (UNBOUNDED_DYNAMIC_DEPENDENCY); ask the author to name the rule literally. Rules called from ordinary (non-control) interface expressions are not available to application users.
  • Response headers. Asset responses carry Cache-Control: private, no-cache with a strong ETag, X-Content-Type-Options: nosniff, Cross-Origin-Resource-Policy: same-origin and Content-Security-Policy: default-src 'none'; sandbox.
  • Neutral refusals. A denied, missing, disabled or unrecorded control receives the same neutral 404 INTERFACE_CONTROL_NOT_AVAILABLE with no-store.
  • Remote code. A control's entry is never loaded from a remote URL; it is always the digest-checked file from the installed archive. Whether that code then loads a provider library is up to the code: cooperating packages do so only when the provider is on, but Inflow does not enforce this.

Residual risks to accept knowingly:

  • The upload is the only trust decision. Anyone holding plugin administration rights can make browser code run for every person who opens an interface that places one of its controls, and Java code run in the plugin runner, with no second person or review step. Grant plugin administration as narrowly as deployment rights. The audit log records every upload with its uploader and fingerprint; Disable and Uninstall stop a plugin; there is no server-wide kill switch.
  • Trusted code, not a sandbox. Uploaded control code runs with the signed-in person's browser access.
  • No browser enforcement of provider origins. The Studio shell has no Content Security Policy that limits scripts to the reviewed origins. The Connects to list is a declaration that the browser does not enforce. Upload only packages from publishers you trust to respect it.
  • A provider receives data as soon as its settings are saved. Saving is the consent; read Receives before you save.
  • Browser keys are public. Restrict them at the provider by referrer and API, and rotate them there if they are misused.
  • Kept versions follow the current package's provider declaration. A kept version is served with the provider declaration of the package that is installed now.

Troubleshooting

What you see Likely cause What to do
The API log shows retiredSettingIgnored key=plugins.expression-functions.security.kill-switch at startup The server's configuration still names the removed kill switch. It is ignored; plugins serve by their own state. Nothing is required. Delete the line from the configuration file or environment to stop the notice. To stop a plugin, use Disable or Uninstall.
An older client or script reports PLUGIN_KILL_SWITCH_ACTIVE Only a server from before the global switch was removed answers this code. Upgrade the server. Current servers never refuse for this reason.
PLUGIN_ID_ALREADY_INSTALLED: "A plugin with this identifier is already installed. A Mixed or Java plugin keeps one active version: Uninstall it first, then upload the new version." You uploaded a new version of an installed Mixed or Java plugin. (A new version of a UI-only plugin is an upgrade and is accepted.) Review the usage list, uninstall, then upload the new version.
PLUGIN_VERSION_CONFLICT: "This plugin version is already installed with different content. Publish a new version." Same version, different bytes. Ask the publisher for a new version number. Never upload lookalike bytes under an existing version.
"Only JAR and ZIP plugin files are supported." / "The plugin file must be 5 MB or smaller." Wrong file or file too large. Use the publisher's packaged archive.
PLUGIN_SECURITY_REJECTED / PLUGIN_STAGE_FAILED The archive failed verification or inspection. Return the archive to the publisher. Do not repackage it yourself.
PLUGIN_HOST_VERSION_UNSUPPORTED, PLUGIN_CONTROL_CONTRACT_UNSUPPORTED or PLUGIN_CONTROL_SDK_UNSUPPORTED on upload The package was built for a different Inflow host version, control contract or SDK major. This server supports control contract 1 and SDK major 1. Ask the publisher for a build that targets this server's versions. Do not edit the manifest yourself.
PLUGIN_CONTROLS_INVALID on upload The manifest's interface-control section is invalid, for example a UI-only package that declares server capabilities. Return the package to the publisher with the exact code and message.
PLUGIN_CONTROL_DEFAULT_INVALID on upload ("control '…' property '…' has a default that does not fit its declared … type: …") A property's declared default does not fit its type, for example a DECIMAL default written as a JSON number. Before SCRUM-5076 such a package was accepted and then blocked publication of every interface that placed the control. Nothing is stored. Return the package to the publisher with the exact code and message; they fix the default, publish a new version, and inflow-control validate reports the same code before upload. The check applies to uploads and upgrades only: a package installed before it, and its kept versions, keep loading after a restart.
PLUGIN_UI_ONLY_NOT_JVM A valid UI-only package (controls, no Java class) reached a path that accepts only Java plugins. The normal upload on Authorization → Plugins accepts UI-only packages, so it does not produce this. Check which route or tool installed the package, and use Authorization → Plugins. Report the route if it was the normal page.
PLUGIN_ASSET_MISSING, PLUGIN_ASSET_TYPE_MISMATCH, PLUGIN_ASSET_SIZE_MISMATCH, PLUGIN_ASSET_DIGEST_MISMATCH, PLUGIN_ASSET_UNDECLARED, PLUGIN_ARCHIVE_INVALID or PLUGIN_ARCHIVE_SYMLINK on upload The archive's files do not match its manifest: a declared asset is missing, has the wrong type, size or SHA-256, an undeclared file is present, or the archive is corrupt or contains a link. Ask the publisher to repackage it with the control tools and to run validate on the exact file. Never repack or edit it yourself.
"Plugin runner unavailable" The plugin runner is down or its heartbeat is stale. This affects mixed and Java functions only. Check the plugin-runner container and its shared IPC volume.
A published form shows Control not available The plugin is disabled or uninstalled, the viewer has no runtime access, or the publication's pinned version is not installed here. For a viewer who opens the interface through an application's runtime access, the control also stays unavailable when its published configuration uses a shape the application runtime does not recognise, such as a binding to data. or record. instead of a form local or input. The same state also appears when the delivered file did not match its reviewed digest, the module failed to start, or it is not compatible with this host. Check the plugin's row and state. Use interface-control-impact to find the version the form pins. If the plugin is active and the viewer has access, look in the browser console of an affected page and give the publisher the exact plugin version and fingerprint. Do not relax digest or compatibility checks.
A map or other provider shows its offline alternative The provider is off, its required settings are not saved in this environment (Needs settings), or its declaration changed. Open Providers and check the environment name, the badge and any Declaration changed notice.
On, but the real map shows the package's error state or a provider error Inflow delivered the configuration, but the provider refused or could not be reached. Common causes are a wrong key, a referrer restriction that does not match the published form's address, the API not enabled, billing not set up, a wrong map ID, or a network that blocks the reviewed origins. Read the provider's error in the browser console. Correct the key and map ID at the provider or under Providers, and check the network path to the Connects to origins. Turn the provider off while you investigate if the failure exposes data unexpectedly.
Provider save refused: "A server secret is set as a vault reference (vault:...), never as the secret itself." You entered a raw secret. Store the secret in the vault and enter its vault: reference.
Provider save refused: "A browser-public value is plain text of at most 512 characters." The value is empty, too long, contains control characters, or looks like a vault reference. Enter the plain public value.
Provider save refused: "Configuration 'key' is not declared by this provider." The key is not in the reviewed declaration. Configure only the keys the review lists.
PLUGIN_PROVIDER_NOT_FOUND The plugin has been uninstalled, or the provider key does not exist. Reload the page.
The Providers dialog shows "The providers cannot be shown right now." The server cannot read provider configuration. Retry later. Check the API logs by plugin id.
A published form request is refused with ACCESS_POLICY_UNAVAILABLE while you test with a development proxy header The published runtime needs an original sign-in credential binding. Sign in normally as an ordinary runtime user to test published forms.
A release review shows a provider as Needs settings or Off The provider is not configured, or not turned on, in this server's environment. Provider settings never travel with a release. Open Authorization → Plugins, choose Providers on the plugin's row, check the environment name, set the required values and save. Review the release again; the provider shows Configured and on. The import is not blocked meanwhile.
A release review shows Not available here The receiving server lacks the exact artifact, or the plugin is disabled or not active there. Follow Move interfaces between environments.

When you report a problem, include the plugin id, version, fingerprint, the environment key, the exact message or code and the time. Do not include browser keys, vault references, secrets or customer data.

Inflow documentation · Published 19 November 2026

Screenshot captions retain their recorded build and capture context.

Type to search articles and their contents.