Topics

Description

The Topics page lets you manage the Kafka topics your scenarios read from and write to, together with their message schemas, without leaving the Designer. Open it with the Topics item of the Designer side menu (path /topics). The page is available when the Topics extension is enabled on your installation (it is in Nussknacker Cloud and in the enterprise installation bundle); see Configuration below.

The topics listed here live in the Kafka cluster the Topics extension is configured with. They are the topics offered by the Topic source and sink (see Topic (Source) and Topic (Sink)), so you can use them to pass events between scenarios. Kafka and the schema registry are the source of truth: the page only reads and changes what is there.

Topics list

The list shows every topic of this instance, sorted by name, with:

• Schema registered or No schema
• Retention: <n>h, or Retention: unlimited when the topic has no time limit

Click a topic to open its details. Use Add topic (top right of the page) to create a new one.

Adding a topic

Add topic opens the Add new topic dialog. The name field is prefilled with a random name, which you can change.

Field	Description
Topic name	Name of the topic. Allowed characters: letters, digits, ., _ and -; at most 200 characters. It must not be the name of an existing topic.
Message schema	No schema, JSON Schema or Avro. With No schema the topic accepts any message, and Nussknacker cannot validate field names and data types of SpEL expressions using it; for JSON messages you can still use dynamic field access. Read this section to understand the role of a topic schema.
Schema	Shown when a schema type is selected; required then. The JSON Schema or Avro schema of the message value, written as JSON.

Under Show advanced options:

Field	Description
Retention time (hours)	For how many hours a message stays available for consumers after being published; a positive integer. When the advanced options stay hidden, the default retention set by the administrator is used.

Click Add topic to create it. The number of partitions, the replication factor and the maximum message size are not set per topic: they come from the configuration.

Topic details

The details page of a topic shows:

• Last messages preview - up to 30 most recent messages on the topic, each with its timestamp. It refreshes every 10 seconds, and on Refresh.
• Properties - Retention time; Max message size is shown after Show advanced.
• Message schema - the latest registered schema, or No schema registered.

and the actions:

• Edit - opens the Edit topic dialog with the same fields as when adding; the name cannot be changed. Changing the schema registers it as a new schema version (the schema registry does not check compatibility with the previous version). Choosing No schema removes the topic's schema. Retention is changed only when you change it under Show advanced options. Confirm with Update topic.
• Clone - opens the Add new topic dialog prefilled with this topic's name, schema and retention, so you can create a similar topic under a new name.
• Remove - deletes the topic together with its schema after you confirm with Remove topic. Messages on the topic are lost, so check first that no scenario uses it.

Limits and errors

• A topic name that is empty, too long or contains other characters is rejected (Invalid topic name).
• Retention must be at least 1 hour.
• Adding a topic whose name is taken fails with Topic [<name>] already exists.
• An installation can limit how many topics it holds; once it is reached, adding fails with Topic limit of <n> reached for this instance.
• A schema can be registered only when the Kafka configuration has a schema registry; otherwise saving a topic with a schema fails with No schema registry is configured for this instance.

Creating a topic from a node

The Topic name parameter of Kafka sources and sinks (including the Topic source and sink) has a Create New Topic button next to it while you edit the node, whenever the Topics extension is enabled. It creates a topic with a random name, no schema and the default retention, and puts its name into the parameter. Open the Topics page afterwards to add a schema or rename it by cloning.

AI assistant

When the Topics extension is enabled, the Designer AI assistant can list topics, read a topic with its schema, preview its last messages, create a topic and update its retention or schema. It cannot delete topics.

Configuration

This section is for administrators. The Topics page consists of the Topics extension of the Designer (the /api/custom/topics API) and a tab in the main menu configuration:

tabs: ${tabs} [
  {id: "topics", url: "nuEnterpriseTopics/tab@/static/topics/remoteEntry.js", title: "Topics", type: "Remote"}
]

The Create New Topic button and the AI assistant tools are available only when this tab is configured.

The extension is configured in the Designer configuration under topicsExtension:

topicsExtension {
  processingType: "streaming"
  topicLimit: 100
  defaultPartitions: 1
  defaultReplicationFactor: 1
  defaultRetentionHours: 24
  maxMessageBytes: 102400
}

Parameter name	Type	Default value	Description
topicsExtension.processingType	string		Processing type (scenario type) whose model configuration supplies the Kafka and schema registry connection, read from components.webhook.config (the webhook-kafka component provider), and the namespace of topic names
topicsExtension.topicLimit	int	no limit	Optional. Maximum number of topics of this instance; adding a topic beyond it is refused
topicsExtension.defaultPartitions	int		Number of partitions of a newly created topic
topicsExtension.defaultReplicationFactor	short		Replication factor of a newly created topic
topicsExtension.defaultRetentionHours	int		Retention (retention.ms) of a new topic when none is given, e.g. by the Create New Topic button
topicsExtension.maxMessageBytes	long		max.message.bytes of a newly created topic - the size of the biggest message it accepts

All parameters except topicLimit are required. When a namespace is configured, topic names are prefixed with it in Kafka, the page shows them without the prefix, and only topics with this instance's prefix are listed. A schema is registered under the <topic>-value subject, and only when schema.registry.url is set in the Kafka properties.