Summary

Every processor in Clockspring has several configuration tabs that control how it runs, how often it executes, how it handles FlowFiles, and how it interacts with attributes, parameters, and controller services. This article explains each tab’s purpose, when you should modify the settings, and common pitfalls to avoid.

1. Settings Tab

Controls general processor behavior and how it responds to failures.

Processor Name

Use clear, descriptive names. This improves debugging, logs, search, and team handoff.

Penalty Duration

If a FlowFile is penalized, it must wait this long before being processed again.

Yield Duration

How long the processor pauses after a failure before attempting to run again.
Yield interacts with retry/backoff behavior.

Bulletin Level

Controls when canvas bulletins appear (INFO, WARN, ERROR).
Use WARN or ERROR to reduce noise.

Automatically Terminate Relationships

Any relationship not routed in the canvas must be terminated here.
All relationships must be handled or terminated.

2. Scheduling Tab

Controls when a processor runs and how often it executes.

Timer Driven

Runs at a fixed interval based on when you clicked Start.

Example:

• Start clicked at 9:01

• Run schedule = 5 min
  Runs at:

• 9:01

• 9:06

• 9:11

• 9:16

Important Notes for Timer Driven

• 0 sec = run continuously (very high throughput, heavy load)

• Run Once ignores the schedule and executes exactly once

• Timer-driven drift is based on start time, not wall-clock time

Caution with Generating Work

If the processor creates FlowFiles or triggers external activity:

• GenerateFlowFile on 0 sec = infinite FlowFiles

• InvokeHTTP on a short timer = constant API hammering

• List processors can repoll too quickly

Always choose timer settings intentionally for starter processors.

CRON Driven

Runs on strict wall-clock time using standard cron expressions.

Starting the processor does not trigger an immediate run.

Example:
CRON: 0 */5 * * * ?
Runs at:

• 9:05

• 9:10

• 9:15

Cron helper

For building expressions: https://crontab.guru

When to use CRON

• Daily reports

• Hourly batch jobs

• Nightly cleanup tasks

• Anything requiring predictable real-world timing

Concurrent Tasks

How many threads this processor can run simultaneously.

Impacts:

• Throughput

• API rate limits

• DB locking

• CPU usage

Use with caution when interacting with external systems.

Run Duration

Run Duration controls how long a processor keeps its execution thread before returning it to the thread pool. Instead of processing one FlowFile per execution cycle, the processor will continue working for the duration you specify.

This setting matters most for processors that benefit from working on many FlowFiles in a single session, where batching improves throughput.

When higher Run Duration helps

Increase the slider when:

• You're working with Split or Merge processors and want them to finish a batch faster

• You have high-volume queues and want to reduce overhead from starting new sessions repeatedly

• You want to reduce load on controller services that get hit repeatedly per session

• You’re trying to drain a backlog more efficiently

• You want fewer checkpoints for stateful processors

In these cases, longer Run Duration keeps the thread active and allows the processor to handle more FlowFiles at once.

When lower Run Duration is better

Keep Run Duration low when:

• The processor interacts with external systems where long sessions block concurrency

• You need fast handoff between processors

• You want the processor to release threads more often so others can run

• You’re working with APIs, databases, or remote systems that should not be hammered continuously

• You want to honor queue backpressure more quickly

Short durations ensure the processor doesn’t monopolize threads.

General guideline

• Default (0 sec): good for most cases.

• Raise slightly (0.1–0.5 sec) to improve throughput for high-volume flows.

• Raise more (0.5–2 sec) only when doing batch-heavy operations or draining large queues.

Avoid setting long durations unless you fully understand the impact. Overuse can starve other processors, especially in smaller clusters.

Execution (Cluster Behavior)

Controls how the processor behaves in a cluster.

• All Nodes – runs independently on every node

• Primary Node Only – only the primary node executes this processor

Use primary-only for:

• polling APIs

• listing files

• retrieving DB offsets

• anything that must run once, not N times

3. Properties Tab

Defines the processor's logic.

Required vs Optional Properties

Missing required properties will make the processor invalid.

Expression Language

Most properties support dynamic values using ${attributes} and can mix attributes + parameters:

#{api_root}/v1/${resource}/${id}

This reduces processor duplication and simplifies flows.

Parameter Sensitivity Rules

• Sensitive processor properties require sensitive parameters

• Non-sensitive processor properties require non-sensitive parameters

If a parameter doesn’t appear, the sensitivity mismatch is why.

4. Relationships Tab

Controls FlowFile routing.

Routing

Processors output FlowFiles to one or more relationships:

• success

• failure

• retry

• dynamically generated ones (e.g., RouteOnAttribute)

All relationships must be routed or terminated.

Retry Behavior

If “retry” is enabled on a relationship:

• The FlowFile remains in the inbound queue

• Backoff doubles each attempt until the max backoff is reached

• After all attempts are exhausted, the FlowFile is transferred to the retry relationship

Retries do not immediately route downstream.

See more about routing and retries here.

5. Comments Tab

Optional but helpful for documenting:

• unusual configuration choices

• expected input/output

• internal runbook references

Best Practices

• Name processors descriptively

• Use attributes + parameters to avoid copy/paste processors

• Be intentional with Timer Driven schedules

• Avoid overusing concurrent tasks

• Document anything unusual in comments

• Only terminate relationships when you’re sure they’re not needed

Related Articles

• What Is a Processor?

• Using Processor Properties Effectively

• Processor Retry, Yield, and Penalty

• Relationships and Routing

• FlowFile Content vs Attributes

• Using Parameters in Clockspring