Best Practices for Attributes

Summary

Attributes drive routing, decisions, lookups, and processor configuration in Clockspring. Using attributes consistently and intentionally makes flows easier to maintain, debug, and promote between environments.

1. Use attributes for decisions - and store small, important data you need later

Attributes shouldn’t contain entire payloads, but they should hold small pieces of data you need after content changes.

Common cases include:

• IDs extracted from JSON (customer.id, transaction.id)

• Timestamps or sequence numbers

• Paging tokens

• Keys needed for a downstream API call

• Hashes of original content before a transformation

• Reference metadata needed after a processor overwrites content

This is intentional and correct when:

• The content is about to be replaced (e.g., by InvokeHTTP, ConvertRecord, Transform, Fetch)

• The value is small and stable

• You need the value later in the flow

Avoid storing:

• entire JSON payloads

• full request/response bodies

• multi-kilobyte strings

• anything better kept in the content repo

Attributes should hold important values, not large structures.

2. Name attributes clearly and predictably

Use a simple naming pattern so attributes mean something at a glance.

Good patterns:

• source.*

• http.*

• db.*

• record.*

• error.*

• route.*

Bad patterns:

• One-letter names

• Ambiguous names (value, data)

• Names that collide with system attributes like uuid

Clear naming avoids confusion and accidental overwrites.

3. Create attributes early in the flow

Set or extract attributes as soon as you have the information.
It simplifies routing logic downstream.

Typical early processors:

• EvaluateJsonPath

• ExtractText

• UpdateAttribute

• HashContent

• ListFile (already provides many)

The earlier attributes exist, the easier the flow is to read and debug.

4. Do not store sensitive data in attributes

Attributes are visible in provenance and logs.

Use parameters or controller services for sensitive values like:

• passwords

• API keys

• OAuth tokens

• private keys

• secrets of any kind

Attributes should never be used as a secret storage mechanism.

5. Know which processors drop or rewrite attributes

Not all processors pass attributes through unchanged:

• Split processors → copy attributes to each fragment

• Merge processors → may keep only selected or "dominant" attributes

• Generate processors → create new FlowFiles (no inherited attributes, but can create new attributes)

• Record processors → add metadata like record counts

Many processors write the error_message attribute so if there are chained errors the most recent error message will be stored.

If attributes disappear unexpectedly, check whether a processor created a new FlowFile.

6. Avoid overwriting attributes accidentally

Frequent mistakes:

• Using UpdateAttribute without conditions

• Reusing generic names (status, type, id)

• Letting upstream processors produce conflicting names

Use namespacing when needed:
 api.status.code
 db.record.count
 route.reason

7. Keep attribute values small

Attributes should be lightweight. Overly large values waste memory and make provenance noisy.

Avoid:

• Entire JSON documents

• CSV payloads

• Images

• Base64-encoded blobs

• Multi-megabyte strings

Instead, extract only the key fields you need.

8. Use attributes to support dynamic behavior

Attributes are ideal for constructing runtime values.

Examples:

• ${customer.id} in API URLs

• ${filename:replace('.csv','.json')}

• ${record.count:gt(0)} for routing

• ${bucket}/${filename} for object storage paths

• ${hash.value} for deduplication keys

Attributes = control plane.
Content = data plane.

9. Use attributes consistently across teams

If multiple people build flows, define a simple standard:

• lowercase keys

• dot-separated namespaces

• consistent naming for flags (is_*, has_*)

• standard core attributes like correlation.id or source.system

This keeps flows predictable and easier to maintain.

Quick rules to remember

• Attributes should be small, meaningful, and safe to reveal.

• Attributes drive logic; content carries data.

• Set attributes early.

• Don’t store secrets in attributes.

• Watch out for processors that generate new FlowFiles.

Related Articles

• FlowFile Content vs Attributes

• How Attributes Move Through a Flow

• Expression Language Basics

• Common Attribute Patterns