Custom processor UIs and content viewers in NiFi 2

Teams building custom processor configuration UIs or content viewers for NiFi 2 need to get the WAR layout, root path and dependency choices right before writing code. This page explains those decisions, the build sequence and what drives effort.

On this page

When a custom UI for a NiFi 2 processor is worth building

A custom UI or content viewer is worth building when the standard NiFi interface cannot show or edit what your team needs. Both are web extensions that ship inside NiFi 2 and need deliberate design, because they run in the same platform as your flows and must follow NiFi's own rules for packaging and web paths. Teams usually reach for one when a processor has many interdependent properties that the generic property grid handles poorly, when operators need to review a complex payload (a binary format, a nested record, a rendered document) before a flow acts on it, or when a configuration step needs guided input that validation alone cannot provide.

Before you commit, test whether the need is really a UI problem. A custom property validator, better property descriptions, or a documented parameter context may solve the same operator problem at lower cost. If a UI is still justified, price its maintenance as carefully as its build. Each NiFi upgrade can change the web layer, so the UI needs regression testing on every 2.x release you adopt, and someone must own its dependencies, security fixes and browser behavior after the first release. Ask any partner to estimate that recurring work separately from the initial build. The NiFi Developer's Guide is the base reference for the extension model, and the NiFi migration guidance is the place to check changes that affect web components between releases. Confirm your target NiFi 2 version against the NiFi download page before you design anything, since the supported web extension contract is what your UI will depend on for years.

What custom UIs and content viewers can do in NiFi 2

Custom UIs and content viewers are the two extension surfaces that reach beyond processor logic into what operators see and configure. Both ship inside a WAR-based web component, so the packaging, the root path contract and the dependency choices decide whether they keep working across NiFi 2 releases. Confirm each hook against the release you run before you commit to a design.

Advanced processor configuration interfaces

A custom configuration UI lets an operator edit a processor's properties through a richer form than the standard property dialog. It matters when a property set has dependencies, validation rules or structured input that a flat list handles poorly. Check which component hooks the NiFi Developer's Guide currently documents for custom processor UIs, and confirm how the UI bundle is loaded, since it runs in the browser next to the NiFi interface and must not assume internal NiFi markup stays stable.

Content viewers for FlowFile data

A content viewer renders FlowFile content in the browser so an operator can inspect a record, document or binary payload from the data provenance or queue views. It is useful for formats NiFi does not display natively, such as domain-specific binary or structured files. Decide early which content types the viewer claims, how large payloads are streamed rather than loaded whole, and how access follows the same authorization rules as the source flow.

WAR layout and packaging

Custom UI and viewer components are packaged as WAR files that NiFi deploys alongside its own web application. The web archive layout, the web descriptor and the bundle manifest must match the component type your release expects, so build the packaging from the current NiFi templates rather than an old example. Keep the WAR separate from processor NARs in your build so a UI change does not force a rebuild of processing logic.

Root path contract changed in 2.0

NiFi 2.0 changed the root path contract that web components use, so a UI built for 1.x may load assets or call endpoints from paths that no longer exist. The migration guidance covers this change and is the first place to check relative URLs, context paths and redirects. Test each component under the reverse proxy and context path your production deployment uses, not only at the root of a local instance.

Servlet-based viewer pattern from 2.5

NiFi 2.5.0 replaced the standard content viewer, previously a Spring Boot application, with a simple Java Servlet implementation and advises custom viewers to follow the same pattern. Building on that pattern gives you a smaller, more predictable deployment and a dependency set that NiFi's own viewer also uses. Confirm the servlet entry points and the content access API against the release you target before writing code.

Avoiding Spring Boot dependencies

A viewer or UI that bundles Spring Boot brings its own container, auto-configuration and version pins, which can clash with the libraries NiFi already loads. Keep the dependency tree to the servlet API and the libraries you genuinely need, and enforce that in the build with a dependency report that fails on unexpected frameworks. Review each upgrade of NiFi for changes to shared libraries, since a pinned version that worked on one 2.x release can conflict with the next.

Which UI approach fits which requirement

This table compares four ways to add UI to NiFi 2: standard property dialogs, a custom configuration UI, a servlet-based content viewer, and a Spring Boot-based viewer. Read each row against your requirement, then check the upgrade risk and the NiFi 2.x release you plan to target before choosing.

ApproachWhen it fitsUpgrade riskWhat to confirm
Standard UI with documented propertiesProcessor settings can be expressed as clear, validated property fields and descriptorsLow, because the UI is maintained by NiFi and follows the component APIThat property descriptors and validators cover your inputs on the target 2.x release
Custom configuration UISettings need multi-step logic, dependent fields or previews that standard property dialogs cannot showMedium to high, since the UI code depends on NiFi front-end internals that can change between releasesWhich front-end extension points the target release exposes and how they are tested after each upgrade
Custom content viewer (servlet pattern)You need to render a FlowFile format NiFi does not display, and the viewer must work alongside the standard viewerLower, since NiFi 2.5.0 moved its own standard viewer to a simple Java Servlet, which is the pattern the migration guidance advisesThat your target release is 2.5.0 or later and that the viewer runs with its own dependencies only
Content viewer built on Spring BootA team already standardizes on Spring Boot and wants to reuse that stack inside the viewerHigh, because the migration guidance advises custom viewers to avoid Spring Boot dependencies, and NiFi's own viewer moved away from itWhether the Spring Boot version and its libraries can be packaged without conflicts in the target NiFi 2.x WAR
Viewer requirement for NiFi 2.0 to 2.4You must support a viewer on a release before the servlet pattern existedHigh, because the servlet-based pattern is documented from 2.5.0 onwardThe exact NiFi 2.x release in your plan and whether a later upgrade is scheduled

How the WAR layout and root path change in NiFi 2.0

Start with the root path, because it is the change most likely to break a custom UI or content viewer without any build error. The NiFi migration guidance describes how the web application root path changed for NiFi 2.0, and your extension should be checked against that contract before anything else. List every URL your WAR assumes: the context path it is deployed under, the endpoints the NiFi UI calls to reach it, and any links your pages generate for scripts, styles or follow-up requests. An extension that hardcodes a 1.x path can package cleanly and still fail at runtime, because the container serves it at a location the NiFi UI does not expect. Confirm the exact paths for your target 2.x release in the guidance, and do not rely on memory of earlier builds.

Next, check the WAR layout itself. The guidance sets out what the web archive must contain and how the servlet container loads it, so compare your Maven packaging output against that layout before the first deployment. Look at the directory structure, the descriptor files and the libraries bundled inside the archive. Treat any difference as a defect to fix before deployment, not as a warning to review later. If the layout check fails, the cause is often a leftover dependency or a packaging plugin carried over from an earlier build, so review the dependency tree of the WAR module as well as the packaging configuration. Record the layout you verified so that later changes to the build can be compared against a known good archive.

In a test deployment, run four checks against a NiFi 2.x instance. First, confirm the WAR deploys without errors and appears in the server log under the expected context. Second, load the UI or viewer at the path the guidance defines and confirm it renders. Third, open a browser developer tools session and confirm that every request the page makes returns successfully, since a single misdirected asset path is easy to miss in the rendered view. Fourth, open a content item from the NiFi UI through your extension and confirm the content displays as expected. If you are still running 1.x, repeat the same checks on a 1.x instance during migration planning so that you can compare the two results.

How a custom NiFi 2 UI moves from design to production

This sequence takes a custom configuration UI or content viewer from a confirmed NiFi 2.x target to a tested, packaged extension that has been proven on a staging cluster before production. Each step closes with an output the team can check before moving on.

  1. Confirm the NiFi 2.x target and Java 21 runtime

    Fix the exact NiFi 2.x minor version the UI will run on, then confirm that the build toolchain, the runtime on each node and the staging environment all use Java 21, which the NiFi administration guide lists as the minimum runtime. Record the target version in the design document, because the UI must be built and tested against the same version it will run on. The output is a signed-off target version and a runtime check on every node.

  2. Choose the UI or viewer pattern

    Decide whether the extension is a processor configuration UI that extends the component's existing dialog or a standalone content viewer, and list the content types and user actions it must support. Confirm the authentication and access expectations with the security team, since the UI will be served inside NiFi's security model. The output is a short written pattern decision that names the content types, the users and the data the viewer may display.

  3. Lay out the WAR and root path

    Create the WAR structure and set the application root path to match the contract that NiFi 2.0 introduced, so NiFi routes requests to the extension correctly. Keep static assets and entry points inside the WAR and avoid assumptions about a path prefix that the deployment may change. The output is a skeleton WAR that deploys and returns a response at its expected root path on a local NiFi 2.x instance.

  4. Build on the servlet pattern without Spring Boot

    Implement the viewer or UI as a plain Java Servlet, following the pattern NiFi 2.5.0 adopted for its standard content viewer, and audit the dependency tree for any Spring Boot artifacts pulled in transitively. Keep the dependency set small so that library versions do not conflict with those NiFi already loads. The output is a dependency report that shows no Spring Boot artifacts and a build that compiles against the chosen NiFi 2.x version.

  5. Test against a running NiFi instance

    Deploy the WAR to a local or development NiFi 2.x instance and exercise every user path, including the configuration dialog, error handling for malformed content and access by users with different roles. Check the browser console and the NiFi application log for errors on each path. The output is a test record that lists each path, the NiFi version tested and the result.

  6. Package the extension for deployment

    Build the final artifact with a repeatable Maven build, record its version and checksum, and document the NiFi 2.x versions it was tested against. Store the build configuration in version control so that the same artifact can be rebuilt after a NiFi upgrade. The output is a versioned artifact with a checksum and a compatibility note that names the tested NiFi versions.

  7. Deploy to staging and run the upgrade test

    Install the artifact on a staging cluster that matches production topology and configuration, then run the test record again on each node. Repeat the test after upgrading staging to the next NiFi 2.x release you plan to run, because UI and viewer behavior can change between releases. The output is a staging sign-off that covers both the current and the upgraded NiFi 2.x version, and that gates the production rollout.

Why the servlet viewer pattern replaced Spring Boot from NiFi 2.5

NiFi 2.5.0 changed the standard content viewer from a Spring Boot application to a simple Java Servlet implementation. The project's migration guidance now advises custom content viewers to follow the same pattern and avoid Spring Boot dependencies. The change matters because the content viewer is a component that NiFi loads and serves alongside its own web application, so its packaging and framework choices affect the whole server. For a developer, the practical meaning is that the reference implementation is now the model to copy, not an application framework to bring along.

  • Reference model: The standard viewer is the example to read when building a custom viewer for NiFi 2.5 or later.
  • Framework choice: A servlet is a plain Java web component, so the viewer carries no application container of its own.
  • Guidance scope: The advice covers custom content viewers, so review any viewer built on Spring Boot before upgrading.
  • Version boundary: The change is tied to NiFi 2.5.0, so earlier 2.x releases may still reflect the older design.
  • Build impact: Remove framework starters from the viewer build and test the servlet mapping against your target release.

Confirm the exact viewer contract for your target NiFi version in the migration guidance and the NiFi source before you start a build.

What drives effort and cost for a custom NiFi UI

This table lists the factors that most change the effort of a custom NiFi configuration UI or content viewer, and how to reduce each one. Read it before requesting a quote so the written scope names the fields, formats, external calls, security model and upgrade commitments that will set the price.

DriverWhy it changes effortHow to keep it downWhat to ask for in a quote
Number of configuration fieldsEach property adds validation, dependency rules, default handling and test cases in the UI and the backendLimit the UI to settings operators change often, and keep the rest as processor properties with defaultsField count, grouped by page, with validation rules listed per field
Validation rules and cross-field logicConditional fields and rules spanning several inputs need careful state handling and more test coverageMove rules that must always hold into the backend, and keep UI checks to usability hintsWhich rules run in the browser, which run server side, and how errors are shown
Content formats the viewer must renderEach format (JSON, XML, Avro, binary, images, custom records) needs its own parser, rendering path and large-file handlingStart with the formats your flows actually carry and treat others as later phasesA list of formats, typical and maximum file sizes, and whether rendering must be streamed
External service calls from the UICalls to outside systems add authentication, timeouts, error states and mocking for testsRoute calls through a backend component with a single client, or defer them to a later releaseNamed services, the auth method each uses, and how failures appear to the user
Security integration with the authentication providerNiFi supports single-user, LDAP, OpenID Connect, SAML 2.0 and X.509 client certificates, and each changes how identity and access reach the UIConfirm which provider your NiFi uses before design starts and reuse NiFi's existing user contextWhich provider is assumed, how authorization is checked for each view, and who tests it
Upgrade cycles across NiFi 2.x releasesEach 2.x release can change APIs, component behavior or the viewer contract, so custom UI code may need reworkPin to one target 2.x release, keep UI code isolated from NiFi internals, and test against each new release before rolloutWhich NiFi 2.x versions are covered, what the upgrade effort includes, and how regression tests are handed over
Packaging and deployment targetWAR layout, classloader isolation and the deployment path for each environment add build and release workUse the same packaging pattern in every environment and automate deploymentBuild outputs, environments covered and the deployment steps the client will run
Documentation and handoverOperators and developers must be able to run and change the UI without the original authorDocument configuration, data flow and test steps as the work proceedsHandover artifacts, training hours included and who maintains them after delivery

Testing and upgrading custom UIs across NiFi 2.x releases

Verify a custom UI in a running NiFi 2 instance before you treat it as finished. Deploy the WAR to an instance on the same release and Java runtime as production, using the minimum runtime listed in the NiFi administration guide. Then walk every path the UI exposes: the root path under the configured context, the configuration dialogs opened from a processor or controller service, and the content viewer opened from a provenance event or queue listing. Test with the content types your users handle, including large and binary files. Record the NiFi version, Java version and browser versions used, so any failure can be reproduced. Also confirm the UI behaves correctly for a user who lacks permission to view the flow.

Treat every NiFi 2.x release as a change to test against, because your UI runs inside the framework it was built for. Keep a regression suite of the same checks and rerun it against each release you plan to adopt before upgrading production. Read the release notes and the NiFi Migration Guidance for changes that affect the web application, the root path contract changed in 2.0, and the 2.5.0 change that moved the standard content viewer from Spring Boot to a simple Java Servlet implementation. If your UI depends on Spring Boot libraries, remove that dependency first, since it ties your UI to framework changes that the standard viewer has already moved away from. Confirm with the project which release line you will target.

Keep the UI aligned with the apache/nifi repository by pinning your build to a specific NiFi version and reviewing the changes to web and viewer code between your current and target releases. The apache/nifi repository on GitHub is the place to trace those changes, and the downloads page shows the current release, which at the time of writing was NiFi 2.12.0, released on September 13, 2026. Assign an owner for each review, schedule it before every planned upgrade, and record the outcome. Processor and controller service unit tests are covered on the sibling page on testing custom processors with nifi-mock, so this section assumes those tests already pass. Ask any implementation partner to show regression results for each target release and a list of the NiFi framework APIs the UI depends on.

How custom UIs connect to the rest of the NiFi platform

Does a custom NiFi UI inherit the platform's login and access rules?

Not automatically. A custom UI is served from its own web application, so it only enforces the access rules you build into it. NiFi authorizes requests on its REST API using the identity it receives, and the supported authentication options are single-user, LDAP, OpenID Connect, SAML 2.0 and X.509 client certificates, while the Kerberos provider is deprecated. Confirm which provider your cluster uses, how the UI obtains the user identity, and that every write path calls the NiFi API with that identity so existing authorization policies still apply. Review the NiFi System Administrator's Guide for the authentication and authorization model before you design the login flow.

Which processor and controller service properties can a custom UI safely configure?

Only the properties the component exposes through its descriptors, validators and allowable values. A configuration UI should read those definitions rather than hard-code property names, so changes in a later release do not silently break it. Confirm which properties are sensitive, which depend on other properties, and which controller services must be enabled before a processor becomes valid. Pay attention to properties that reference parameter contexts, since a UI that writes literal secrets into a flow bypasses the sensitive value handling your security team expects.

How do a custom UI and its processors stay in sync during upgrades?

The UI and the processor bundle must agree on property names, allowable values and the expected shape of the component's configuration. When either side changes, the other can fail without an obvious error. Plan for this by pinning the NiFi version the UI is tested against, reviewing the migration notes for every target release, and running the UI against a staging cluster before each upgrade. The NiFi Migration Guidance lists the changes between major versions that affect extensions and should be part of the upgrade checklist.

Can a flow registry version a custom UI or only the flows it configures?

A Git-based flow registry versions flows, meaning the process group definitions and their component settings. It does not version the UI or the NAR that contains it. NiFi 2 includes Flow Registry Clients for GitHub and GitLab, which store flows in a Git repository. Decide where the UI build artifacts live, how they are released alongside the NAR, and how a flow that depends on a particular UI version is documented. Confirm with your team whether flows reference extension versions that must be deployed first, because a missing bundle will prevent a versioned flow from loading.

What does packaging and CI need to cover for a NiFi UI extension?

The build has to produce the NAR for the processor or service, the web application for the UI or viewer, and a test path that exercises both. Your CI pipeline should run unit tests against the processor, build the UI with the same toolchain each time, and deploy to a non-production NiFi cluster before promotion. Confirm the Java version your build targets against the minimum runtime in the administration guide, which lists Java 21, and confirm the packaging layout with the team that maintains your NAR structure. Automated browser tests are useful, but they should verify behavior that matters to operators, not only that the page loads.

Which external systems can a content viewer read from, and what does that add?

A content viewer reads FlowFile content through NiFi, but it may also call external systems for lookups, metadata or rendering. Every outbound call adds a network path, a credential to protect and a failure mode the viewer must handle. Confirm which systems the viewer needs, whether it reads only content it is authorized to display, and how it avoids exposing sensitive data in its logs. Also confirm the network path from the NiFi nodes to each system, since a viewer that works on a developer workstation may be blocked in a segmented production network.

Should a content viewer use Spring Boot or a plain servlet?

NiFi 2.5.0 moved its standard content viewer from a Spring Boot application to a simple Java Servlet implementation, and the NiFi Migration Guidance advises custom content viewers to follow that pattern and avoid Spring Boot dependencies. The practical effect is a smaller dependency tree and fewer library conflicts with NiFi's own classpath. Confirm the NiFi version range you support, check the viewer's dependencies for conflicting frameworks, and review the NiFi Migration Guidance before choosing the framework. Treat a Spring Boot viewer built for NiFi 2.4 or earlier as a candidate for rework.

Who owns the UI after the first release, and what does that cost?

The team that builds the UI owns its compatibility with each NiFi release, its dependencies, its security patches and its test suite. Cost comes mainly from ongoing maintenance: each NiFi upgrade, each framework update and each change to the processor it configures can require rework. Ask any partner to separate the initial build from a retained support arrangement, and to state which NiFi versions they will test against. DeployOpen plans, builds and supports extensions like these in your infrastructure on a fixed scope agreed in writing, and ongoing support is available as a retainer.

What the team should hand over and keep after launch

A custom UI or content viewer is only maintainable if the handover includes everything needed to rebuild it, redeploy it and roll it back without the original developer. The core set is the source repository, the Maven build files with the parent and dependency versions pinned, the packaged WAR artifacts with their checksums, the test evidence from running the UI against the NiFi 2 release the team actually operates, and the upgrade notes for each 2.x target the team expects to move to. Ask for these as named items in the written scope, so acceptance can be checked against a list rather than a demo.

The upgrade notes deserve the most attention. For each 2.x target, they should record which NiFi REST endpoints and UI extension points the component calls, whether the content viewer still follows the servlet-based pattern from NiFi 2.5.0 with no Spring Boot dependencies, what changed in the root path contract for the deployment, and which tests were rerun. Confirm with the vendor's migration guidance and release notes at the time of each upgrade, since the contract details depend on the target version. The runbooks should cover deployment to each environment, how to replace the WAR on a running NiFi node, how to roll back to the previous WAR, and who signs off each step.

DeployOpen plans and documents these deliverables as part of the fixed scope, so the handover is agreed before build work starts. Ongoing work after launch, such as reviewing each new NiFi 2.x release, rerunning the UI tests, updating the WAR and refreshing the runbooks, can be covered by a retainer. Ask any provider to state in writing which of these items they will maintain, how often they will review upgrade notes, and what happens to the source and build pipeline if the engagement ends. Your own team should own the repository, the artifact store and the change approval process from day one.

How DeployOpen scopes and delivers NiFi custom UI work

DeployOpen is a Chainscore Labs company that plans, implements, customizes, tests, documents and supports self-hosted open-source platforms inside your own infrastructure. For custom processor UIs and content viewers in NiFi 2, we start from a written scope that names the NiFi 2.x release, the UI or viewer requirements and the packaging target, then build and hand over the work in your environment.

How we scope

  • Written scope names the target NiFi 2.x release and the processors or controller services that need a custom configuration UI.
  • Scope records whether a content viewer is needed and which media types or formats it must display.
  • Scope confirms whether the viewer is packaged as a servlet-based WAR following the NiFi 2.5 standard viewer pattern.

How we build

  • We check the root path contract from NiFi 2.0 against every custom UI and viewer endpoint before writing code.
  • Viewers are built as plain Java Servlet applications that avoid Spring Boot dependencies, keeping the WAR layout and classpath predictable.
  • Each build is tested against the NiFi version you run, including browser checks of configuration dialogs and viewer rendering.

How we hand over

  • Handover includes source, built WAR files, deployment steps and the version matrix tied to each NiFi 2.x release.
  • Documentation covers how the UI authenticates through NiFi, what data the viewer reads and how to roll it back.
  • Your team receives a walkthrough of upgrade checks to run when moving to a later NiFi 2.x release.

How we support

  • Ongoing support for custom UIs and viewers is available as a retainer covering NiFi upgrades and dependency changes.
  • Retainer work includes re-testing UIs and viewers against each new NiFi 2.x release before you move production flows.
  • Support scope, response expectations and upgrade cadence are confirmed in writing before the retainer starts.

Talk to our team.

Tell us what you're working on, whether it's a deployment, an audit, a security test or a cyber range. You'll speak with an engineer who can help you scope it.

  • 30-minute call: free, with no obligation.
  • NDA on request: we can sign before you share details.
  • Clear next steps: a scope and plan after the call.