Topic XML

Export, edit, and import topic XML files for topic data backups and manual editing

Use topic XML to import and export topic data, and to edit topic rules and other components in a text editor. Manual edits can be more efficient than using the interface for certain scenarios, including:

Merging topics to a single entity
Separating overly broad topic rules into multiple, more granular topics
Applying attributes like segments, rule groupings, or exact matches to multiple topics
Bulk renaming for specific keywords or word groups, such as updating wifi to the canonical form wi_fi

Editing topic XML allows for efficient and precise control over:

Topic rule hierarchy
Rule expressions and attributes
Duplication or alteration of complex logic across different languages or segments

Important: However you modify your topic rules, always create a backup of topic XML data before editing so you can restore topic rules and attributes to their original state if erroneous or unintended changes occur.

Before you begin

Prepare for editing by generating two exports from the Topics screen. Use one file to pull existing rules to copy or move, and the other file to place new and modified rules. This second file is the one you will eventually import back into Experience Cloud.
Review the topic hierarchy, rule components, and word matching used in your topics.

Topic hierarchies generally have two or three levels, with topic granularity increasing at each level. In the Admin Suite UI, this is displayed as a nested structure. In topic XML, the hierarchy is defined by the topic-rules element's parentTopicName attribute. If topic-rules does not have parentTopicName, it defines a parent topic.
Understand topic XML structure, how it relates to the hierarchy, and element requirements. Topic XML follows a strict nested structure that must be maintained:
- Topic XML must have a top-level topic-rules-list element.
- Topic language is specified with the language attribute in language-rules elements.
- Each rule element must have two rule-section elements — one for positive conditions, and one for negative conditions — even if they are empty.
- Rule groups are defined by the rule element's concept attribute at the rule level.
- Standard and compound topics use different elements to define their rule structure. Standard topics define rules with rule and rule-section elements.
- Compound topics use conversational-rule, topic-condition, and conversational-block elements in place of standard topic structural elements, and they reference standard topics with the conversational-block element's referencedTopicName attribute.
When merging topics or topic export files, ensure the file header and footer tags are correct and closed, and remove any additional section headers from secondary exports; the imported file must have only one primary header.
Imported XML files must end with these tags:
```
                        </rule-section>
                        <rule-section/> /*if a second rule-section is not already present*/
			    </rule>
            </rules>
        </language-rules>
    </topic-rules>
</topic-rules-list>
```

Topic rule match logic

Rules use different elements for different logic types.

AND Logic: Multiple <rule-section> blocks require at least one match from every section.
OR Logic: The <rule-or> element satisfies a section if any contained expression matches.
Positive/Negative Conditions: The first section defines required terms; subsequent sections exclude feedback containing specified terms
Proximity (NEAR_WORDS): Uses [Distance, Order] parameters (e.g., [5, N]) to define word gaps and sequence flexibility. Distance is an integer, and Order is N for nearby in either direction or O (uppercase letter o) for words that must occur in the order defined in the rule to be a match.

Word matching for topic rules

Word-level matching is defined in the rule-expr element's expr attribute that specifies the word, word group, or user feature.

Append !e to specify non-case-sensitive exact matching.

Append !ec to specify case-sensitive exact matching.

For example, <rule-expr expr="renew!e"/> specifies non-case-sensitive exact matching for the word renew.

Standard topic example

The following XML example is a complete rules list for two rules in one topic named Testing123. This example is a top-level topic with rules, which is not recommended.

<topic-rules-list>
    <topic-rules topicName="Testing123" previousTopicName="User Features - All Verticals">
        <language-rules language="ENGLISH">
            <rules>
                <rule>
                    <rule-section>
                        <rule-or>
                            <rule-expr type="SINGLE_WORD" expr="word1" /> 
                        </rule-or> 
                    </rule-section> 
                    <rule-section>
                        <rule-or>
                            <rule-expr type="SINGLE_WORD" expr="not_word2" />
                        </rule-or>
                    </rule-section>
                </rule>
                <rule> 
                    <rule-section>
                        <rule-or> 
                            <rule-expr type="NEAR_WORDS" expr="word1,word2 [5, N]" /> 
                        </rule-or> 
                    </rule-section> 
                    <rule-section /> 
                </rule>
            </rules>
        </language-rules>
        <topic-definition description="Example required description" />
    </topic-rules>
</topic-rules-list>

Languages are specified with the language-rules element. To write rules for multiple languages, add additional language-rules elements under the topic-rules element.

The first rule:

                <rule>
                    <rule-section>
                        <rule-or>
                            <rule-expr type="SINGLE_WORD" expr="word1" /> 
                        </rule-or> 
                    </rule-section> 
                    <rule-section>
                        <rule-or>
                            <rule-expr type="SINGLE_WORD" expr="not_word2" />
                        </rule-or>
                    </rule-section>
                </rule>

Negative conditions are expressed in a rule element's second rule-section element. The second rule example does not have any negative conditions, but it does include an empty negative condition block. This second block is required.

The second rule:

                <rule> 
                    <rule-section>
                        <rule-or> 
                            <rule-expr type="NEAR_WORDS" expr="word1,word2 [5, N]" /> 
                        </rule-or> 
                    </rule-section> 
                    <rule-section /> 
                </rule>

Rule type is specified in a rule-expr element's type attribute.

Standard topic example with rule groups

The following example topic includes 4 rule groups: Bathroom, Waiting Area, Food & Drinks, and Media.

<topic-rules-list>
	<topic-rules topicName="Dealership - Amenities" topicType="RULE" parentTopicName="Dealership">
		<language-rules language="ENGLISH">
			<rules>
				<rule concept="Bathroom">
					<rule-section>
						<rule-or>
							<rule-expr type="SINGLE_WORD" expr="toilet" />
						</rule-or>
					</rule-section>
					<rule-section />
				</rule>
				<rule concept="Waiting Area">
					<rule-section>
						<rule-or>
							<rule-expr type="NEAR_WORDS" expr="waiting,area [5, N]" />
						</rule-or>
						<rule-or>
							<rule-expr type="SINGLE_WORD" expr="relax" />
						</rule-or>
					</rule-section>
					<rule-section />
				</rule>
				<rule concept="Waiting Area">
					<rule-section>
						<rule-or>
							<rule-expr type="NEAR_WORDS" expr="waiting,area [5, N]" />
						</rule-or>
						<rule-or>
							<rule-expr type="SINGLE_WORD" expr="warm" />
						</rule-or>
					</rule-section>
					<rule-section />
				</rule>
				<rule concept="Waiting Area">
					<rule-section>
						<rule-or>
							<rule-expr type="NEAR_WORDS" expr="waiting,area [5, N]" />
						</rule-or>
						<rule-or>
							<rule-expr type="SINGLE_WORD" expr="cold" />
						</rule-or>
					</rule-section>
					<rule-section />
				</rule>
				<rule concept="Food &amp; Drinks">
					<rule-section>
						<rule-or>
							<rule-expr type="SINGLE_WORD" expr="cookie" />
						</rule-or>
					</rule-section>
					<rule-section />
				</rule>
				<rule concept="Food &amp; Drinks">
					<rule-section>
						<rule-or>
							<rule-expr type="SINGLE_WORD" expr="biscuit" />
						</rule-or>
					</rule-section>
					<rule-section />
				</rule>
				<rule concept="Food &amp; Drinks">
					<rule-section>
						<rule-or>
							<rule-expr type="NEAR_WORDS" expr="chocolate,hot [5, N]" />
						</rule-or>
					</rule-section>
					<rule-section />
				</rule>
				<rule concept="Waiting Area">
					<rule-section>
						<rule-or>
							<rule-expr type="NEAR_WORDS" expr="waiting,area [5, N]" />
						</rule-or>
						<rule-or>
							<rule-expr type="SINGLE_WORD" expr="pleasant" />
						</rule-or>
					</rule-section>
					<rule-section />
				</rule>
				<rule concept="Waiting Area">
					<rule-section>
						<rule-or>
							<rule-expr type="NEAR_WORDS" expr="waiting,area [5, N]" />
						</rule-or>
						<rule-or>
							<rule-expr type="SINGLE_WORD" expr="comfortable" />
						</rule-or>
					</rule-section>
					<rule-section />
				</rule>
				<rule concept="Media">
					<rule-section>
						<rule-or>
							<rule-expr type="SINGLE_WORD" expr="tv" />
						</rule-or>
					</rule-section>
					<rule-section>
						<rule-or>
							<rule-expr type="SINGLE_WORD" expr="ad" />
						</rule-or>
					</rule-section>
				</rule>
				<rule concept="Waiting Area">
					<rule-section>
						<rule-or>
							<rule-expr type="NEAR_WORDS" expr="wait,area [5, N]" />
						</rule-or>
						<rule-or>
							<rule-expr type="SINGLE_WORD" expr="drink" />
						</rule-or>
					</rule-section>
					<rule-section />
				</rule>
				<rule concept="Waiting Area">
					<rule-section>
						<rule-or>
							<rule-expr type="NEAR_WORDS" expr="wait,area [5, N]" />
						</rule-or>
						<rule-or>
							<rule-expr type="SINGLE_WORD" expr="comfortable" />
						</rule-or>
					</rule-section>
					<rule-section />
				</rule>
				<rule concept="Media">
					<rule-section>
						<rule-or>
							<rule-expr type="SINGLE_WORD" expr="magazine" />
						</rule-or>
					</rule-section>
					<rule-section />
				</rule>
				<rule concept="Media">
					<rule-section>
						<rule-or>
							<rule-expr type="SINGLE_WORD" expr="newspaper" />
						</rule-or>
					</rule-section>
					<rule-section />
				</rule>
				<rule concept="Food &amp; Drinks">
					<rule-section>
						<rule-or>
							<rule-expr type="SINGLE_WORD" expr="refreshment" />
						</rule-or>
					</rule-section>
					<rule-section />
				</rule>
				<rule concept="Media">
					<rule-section>
						<rule-or>
							<rule-expr type="SINGLE_WORD" expr="wifi" />
						</rule-or>
					</rule-section>
					<rule-section />
				</rule>
				<rule concept="Food &amp; Drinks">
					<rule-section>
						<rule-or>
							<rule-expr type="SINGLE_WORD" expr="coffee" />
						</rule-or>
					</rule-section>
					<rule-section />
				</rule>
				<rule concept="Food &amp; Drinks">
					<rule-section>
						<rule-or>
							<rule-expr type="SINGLE_WORD" expr="tea" />
						</rule-or>
					</rule-section>
					<rule-section />
				</rule>
				<rule concept="Bathroom">
					<rule-section>
						<rule-or>
							<rule-expr type="SINGLE_WORD" expr="restroom" />
						</rule-or>
					</rule-section>
					<rule-section />
				</rule>
				<rule concept="Bathroom">
					<rule-section>
						<rule-or>
							<rule-expr type="SINGLE_WORD" expr="bathroom" />
						</rule-or>
					</rule-section>
					<rule-section />
				</rule>
				<concepts>
					Bathroom
				</concepts>
				<concepts>
					Waiting Area
				</concepts>
				<concepts>
					Food & Drinks
				</concepts>
				<concepts>
					Media
				</concepts>
			</rules>
		</language-rules>
         <topic-definition description="Example topic description for a topic with rule groups" />
	</topic-rules>
</topic-rules-list>

Rule groups are defined for the topic with concepts elements:

				<concepts>
					Bathroom
				</concepts>
				<concepts>
					Waiting Area
				</concepts>
				<concepts>
					Food & Drinks
				</concepts>
				<concepts>
					Media
				</concepts>

Rules are assigned to rule groups with the rule element's concept attribute. Rules in the same group do not have to be defined together in topic XML:

				<rule concept="Bathroom">
					<rule-section>
						<rule-or>
							<rule-expr type="SINGLE_WORD" expr="toilet" />
						</rule-or>
					</rule-section>
					<rule-section />
				</rule>
[...]
				<rule concept="Bathroom">
					<rule-section>
						<rule-or>
							<rule-expr type="SINGLE_WORD" expr="restroom" />
						</rule-or>
					</rule-section>
					<rule-section />
				</rule>
				<rule concept="Bathroom">
					<rule-section>
						<rule-or>
							<rule-expr type="SINGLE_WORD" expr="bathroom" />
						</rule-or>
					</rule-section>
					<rule-section />
				</rule>

Topic definition example

The following example shows a standard topic rule with all topic definition components included.

<topic-rules-list>
	<topic-rules topicName="Topic definition examples" topicType="RULE">
		<language-rules language="ENGLISH">
			<rules />
		</language-rules>
	</topic-rules>
     <topic-rules topicName="Description + inclusion + exclusion" topicType="RULE" parentTopicName="Topic definition examples">
		<language-rules language="ENGLISH">
			<rules>
				<rule>
					<rule-section>
						<rule-or>
							<rule-expr type="NEAR_WORDS" expr="mobile,deposit [5, N]" />
						</rule-or>
					</rule-section>
					<rule-section />
				</rule>
			</rules>
		</language-rules>
		<topic-definition description="Feedback from retail banking customers regarding the process, ease of use, or failures when using the mobile app check-deposit feature">
			<relevant-comment>
				The mobile app check-deposit feature is very good
			</relevant-comment>
			<relevant-comment>
				The mobile app check-deposit feature is very bad
			</relevant-comment>
			<irrelevant-comment>
				The in-person check-deposit experience is very bad
			</irrelevant-comment>
			<irrelevant-comment>
				The in-person check-deposit experience is very good
			</irrelevant-comment>
			<relevant-keyword>
				on my phone
			</relevant-keyword>
			<irrelevant-keyword>
				in-person
			</irrelevant-keyword>
			<irrelevant-keyword>
				physical location
			</irrelevant-keyword>
		</topic-definition>
	</topic-rules>
</topic-rules-list>

Topic definition description:

		<topic-definition description="Feedback from retail banking customers regarding the process, ease of use, or failures when using the mobile app check-deposit feature"> 
...
		</topic-definition

Example inclusion comments:

			<relevant-comment>
				The mobile app check-deposit feature is very good
			</relevant-comment>

Example inclusion keywords and phrases:

			<relevant-keyword>
				on my phone
			</relevant-keyword>

Example exclusion comments:

			<irrelevant-comment>
				The in-person check-deposit experience is very bad
			</irrelevant-comment>

Example exclusion keywords and phrases:

			<irrelevant-keyword>
				physical location
			</irrelevant-keyword>

Compound topic example

Compound topics use conversational-rule, topic-condition, and conversational-block elements in place of standard topic structural elements, and they reference standard topics with the conversational-block element's referencedTopicName attribute.

The following example shows a compound topic that references two standard topics: Brand - Competitor Mentions and Appointments - Reschedule/Flexibility. The latter is referenced in multiple speaker contexts.

<topic-rules-list>
	<topic-rules topicName="Test_Compound_Rule (2)" topicType="COMPOUND">
		<compound-topic-rules>
			<conversational-rule targetCommentFieldType="CONVERSATIONAL">
				<topic-condition>
					<conversational-block referencedTopicName="Brand - Competitor Mentions" />
				</topic-condition>
			</conversational-rule>
			<conversational-rule targetCommentFieldType="CONVERSATIONAL">
				<topic-condition>
					<conversational-block referencedTopicName="Appointments - Reschedule/Flexibility" />
					<conversational-block referencedTopicName="Appointments - Reschedule/Flexibility" participant="AGENT" />
					<conversational-block referencedTopicName="Appointments - Reschedule/Flexibility" participant="CUSTOMER" />
					<phrase-number-conversational-span size="1" />
				</topic-condition>
				<conversational-condition>
					<proximity-condition direction="AFTER">
						<phrase-percentage-conversational-span size="99" />
					</proximity-condition>
					<conversational-event-descriptor eventType="BEGINNING_OF_CONVERSATION" />
				</conversational-condition>
			</conversational-rule>
		</compound-topic-rules>
         <topic-definition description="Example topic description for compound topic" />
	</topic-rules>
</topic-rules-list>

Rule with reference to the standard topic Brand - Competitor Mentions and with Agent or Customer as the speaker source:

			<conversational-rule targetCommentFieldType="CONVERSATIONAL">
				<topic-condition>
					<conversational-block referencedTopicName="Brand - Competitor Mentions" />
				</topic-condition>
			</conversational-rule>

Rule with multiple references to the standard topic Appointments - Reschedule / Flexibility for multiple speaker sources:

			<conversational-rule targetCommentFieldType="CONVERSATIONAL">
				<topic-condition>
					<conversational-block referencedTopicName="Appointments - Reschedule/Flexibility" />
					<conversational-block referencedTopicName="Appointments - Reschedule/Flexibility" participant="AGENT" />
					<conversational-block referencedTopicName="Appointments - Reschedule/Flexibility" participant="CUSTOMER" />
					<phrase-number-conversational-span size="1" />
				</topic-condition>
				<conversational-condition>
					<proximity-condition direction="AFTER">
						<phrase-percentage-conversational-span size="99" />
					</proximity-condition>
					<conversational-event-descriptor eventType="BEGINNING_OF_CONVERSATION" />
				</conversational-condition>
			</conversational-rule>

Phrase proximity for standard topics referenced in the same conversational-rule block, defined with the phrase-number-conversational-span element's size attribute:
```
					<proximity-condition direction="AFTER">
						<phrase-percentage-conversational-span size="99" />
					</proximity-condition>
```
Topic occurrence location for standard topics referenced in the same conversational-rule block, defined with the conversational-event-descriptor element's eventType attribute:
```
					<conversational-event-descriptor eventType="BEGINNING_OF_CONVERSATION" />
```

Topic XML elements


Element	Attributes	Description	Required	Example
topic-rules-list	-	Top-level container for all topic XML	Yes	<topic-rules-list> ...
topic-rules	topicName, topicType, parentTopicName, previousTopicName	Defines a topic and its hierarchy and ordering attributes	Yes	<topic-rules topicName="Brand" ...>
language-rules	language, translatedName, segment	Container for topic XML specific to a certain language	No	<language-rules language="ENGLISH">...
rules	-	Container for `rule` and `concepts` elements	Yes	<rules>...
rule	concept	A single rule's logic with an optional `concept` (rule group) attribute	Yes	<rule concept="Change">...
rule-section	-	Container for `rule-or` elements Each `rule` element has two `rule-section` elements. The first is for positive rules. The second is for negative rules. Both elements are required, but each may be empty. All `rule-section` elements must evaluate to true to trigger a match (AND logic).	Yes	<rule-section />
rule-or	-	Container for `rule-expr` elements in which any child expression can trigger the rule (OR logic)	Yes	<rule-or>...
rule-expr	type, expr	Defines the search type (e.g., SINGLE_WORD) and the specific query string. This is the lowest level of topic rule logic.	Yes	<rule-expr type="SINGLE_WORD" expr="rebook" />
concepts	-	Defines rule groups at the topic level	No	<concepts>Flexibility</concepts>
topic-definition	description	Human-readable explanation of what the topic is intended to capture; includes required description; may contain optional keyword and phrases elements	No	<topic-definition description="Feedback from retail banking customers regarding the process, ease of use, or failures when using the mobile app check-deposit feature" />
relevant-comment	-	Optional example of verbatim comments or phrases to be referenced for new inclusion rules	No	<relevant-comment> The mobile app check-deposit feature is very good </relevant-comment>
irrelevant-comment	-	Optional example of verbatim comments or phrases to be referenced for new exclusion rules	No	<irrelevant-comment> The in-person check-deposit experience is very good </irrelevant-comment>
relevant-keyword	-	Optional example of a keyword or phrase to be referenced for new inclusion rules	No	<relevant-keyword> on my phone </relevant-keyword>
irrelevant-keyword	-	Optional example of a keyword or phrase to be referenced for new exclusion rules	No	<irrelevant-keyword> physical location </irrelevant-keyword>
compound-topic-rules	-	Container for all rules in compound topics	Required only for compound topics	<compound-topic-rules>...
conversational-rule	targetCommentFieldType	Container for an individual compound topic rule	Required only for compound topics	<conversational-rule targetCommentFieldType="CONVERSATIONAL">...
topic-condition	-	Container for individual rule expressions for compound topics	Required only for compound topics	<topic-condition>...
conversational-block	referencedTopicName, participant	Individual rule expression for a compound topic that references a standard topic and optional speaker	Required only for compound topics	<conversational-block referencedTopicName="Appointments - Reschedule/Flexibility" participant="AGENT" />
phrase-number-conversational-span	size	Defines phrase proximity requirements for the standard topics referenced in a compound topic	No	<phrase-number-conversational-span size="1" />
conversational-condition	-	Defines location requirements for match occurrence in the conversation; for example, the beginning or end of the conversation	No	<conversational-condition>...
proximity-condition	direction	Defines the `direction` of the conversation to be considered for a match given the `size` attribute of the `phrase-percentage-conversational-span` element	No	<proximity-condition direction="AFTER">...
phrase-percentage-conversational-span	size	Defines the `size` of the portion of the conversation to be considered for a match	No	<phrase-percentage-conversational-span size="99" />
conversational-event-descriptor	eventType	Defines the type of conversational event used to distinguish one part of the conversation from another	No	<conversational-event-descriptor eventType="BEGINNING_OF_CONVERSATION" />

Topic XML element attributes


Attribute	Element	Description	Example values
topicName	topic-rules	Unique, human-readable identifier for a topic	Appointments
topicType	topic-rules	Defines the category of the topic (for example, a standard rule-based topic)	RULE COMPOUND
parentTopicName	topic-rules	Defines a child topic's parent in the topic hierarchy. Parent topics do not include this attribute.	Brand Communication Dealership
previousTopicName	topic-rules	Defines the display order on the Topics screen for topics at the same hierarchy level.	Product - Quality
language	language-rules	Specifies the language for a topic or for nested rules	FRENCH
translatedName	language-rules	The display name for the topic in the target language.	Comunicación
segment	language-rules	Specifies segments for a topic or for nested rules	<language-rules language="ENGLISH" segment="test_segment">...
concept	rule	Specifies rule group association at the rule level.	Food & Drinks
type	rule-expr	Defines the matching logic type for the expression. SINGLE_WORD specifies a single word to be matched. NEAR_WORDS specifies one or more words to be matched that must be within a certain proximity to each other.	SINGLE_WORD NEAR_WORDS
expr	rule-expr	Search query string or reference. The `NEAR_WORDS` type uses `[Distance, Order]` parameters (e.g., `[5, N]`) to define word gaps and sequence flexibility. Distance is an integer, and Order is N for nearby in either direction or O (uppercase letter o) for words that must occur in the order defined in the rule to be a match. Append `!e` to specify non-case-sensitive exact matching. Append `!ec` to specify case-sensitive exact matching. Use an octothorpe `#` to specify a word group. To specify a user feature, use its canonical form.	`rebook` `change,time [5, N]` `#parts_en` `call_center` `renew!e`
description	topic-definition	Required, human-readable text string describing the topic's purpose or goal	Identifies feedback about...