Controller Services Overview

Modified on Thu, 11 Dec, 2025 at 9:34 PM

Summary

Controller services provide shared configuration that processors can reuse. They handle things like database connections, caches, SSL settings, and record readers. If a processor needs an external resource or a reusable config, it almost always gets that from a controller service.

Why this matters

Clockspring flows rely on controller services for consistency, security, and maintainability. Without them, you’d have duplicate settings on every processor, making updates painful and error-prone.

What a controller service actually is

A controller service is a reusable “connection object” or configuration unit that lives outside the processor.
Processors reference it instead of holding their own independent settings.

Simple example:
Instead of configuring a database hostname, port, username, password, and pool settings on five different processors, you set it once in a DBCPConnectionPool controller service and all processors point to it.

What controller services are used for

Common categories:

Database access
DBCPConnectionPool used by QueryDatabaseTable, PutDatabaseRecord, etc.

Caching and deduplication
MapCache or SetCache used by DetectDuplicate, LookupAttribute, enrichment flows.

Record readers and writers
JSONReader, CSVReader, AvroReader, RecordSetWriters.

Security and SSL
SSLContextService used by InvokeHTTP, ListenHTTP, LDAP processors.

HTTP/REST client configuration
Shared timeouts, authentication, and connection settings.

Why controller services exist

One update applies everywhere
Clear separation between “flow logic” and “environment/config”
Consistent security handling
Easier deployments between Dev, Test, Prod
Avoids config drift across processors
Reduces the chance of mismatched credentials or duplicate mistakes

When you use a controller service

In most cases:
If a processor has a property that expects a controller service API, you must use one.
There isn’t a choice. It’s required by design.

You only use processor-level configuration when a processor does not support a controller service for a given property.

How processors interact with controller services

A processor references a controller service by selecting it in the property list
The processor uses that service for every FlowFile it processes
If the controller service is disabled, all processors depending on it stop or error
Changing a controller service affects every processor that uses it

Practical example

You have three processors that write to PostgreSQL:

PutDatabaseRecord
ExecuteSQL
PutSQL

All three should point at the same DBCPConnectionPool service.
If the database password rotates, you update the service once.
Every processor continues working with no changes.