Load Related Topic

Walks the relationship graph out from one topic and puts the topics it finds into the stash. Use it when you already know which topic you are standing on and want the changesets under a release, the release above a changeset, or everything hanging off an incident.

Reach for Get topics that matches conditions instead when you have no starting topic and want to search by category, status or a query. That op searches the whole collection; this one only ever returns topics reachable from the mid you give it.

Nothing is written to the stash unless you fill in Return Key on the op's Options tab. Leave it empty and the op does the work, throws the result away and moves on without a warning.

Fields

Mid

The topic to start from. Required. Takes a literal mid such as topic-100, or a ${var} placeholder that resolves to one, which is the usual case: ${topic_mid} in a workflow rule, ${changesets.0.mid} when a job already loaded its changesets.

A mid that does not exist stops the rule with a "record not found" error. Same result when the placeholder does not resolve, because the unresolved text is passed through as a literal name. Guard the op with IF var condition THEN and a NOT EMPTY test when the variable might be missing.

Only one starting point is accepted. A comma-separated list is treated as a single odd name and fails.

Query type

Which direction to walk. Not free text, pick one of three.

Query type	Returns
children	topics that hang below the starting topic, such as the changesets inside a release
parents	topics that the starting topic hangs below, such as the release holding a changeset
related	both directions at once

children is the default and is what you get if the field was never touched.

Filter statuses

Restricts the result to topics sitting in the statuses you pick. Multi-select; pick as many as you like. Leave it empty and status is not considered at all.

Not in statuses

Flips Filter statuses into an exclusion: everything except those statuses comes back.

This checkbox does nothing on its own. With Filter statuses empty there is nothing to invert, so ticking it changes no results and reports no problem. It is the most common way to configure this op and get an unexpectedly wide answer.

Filter categories

Restricts the result to topics in the categories you pick. Multi-select, and always an inclusion. There is no exclusion switch for categories, unlike statuses.

Empty means every category. The op does no permission checking of its own, so a category the user firing the rule cannot normally see still comes back.

Depth

How many relationship hops to follow. 1 means direct neighbours only, and is the default.

Two traps live here. The first: blank or 0 means no limit. The op then keeps walking until it has visited everything connected to the starting topic, which on a mature database can be most of the graph and can take a long time. Always put a number in.

The second: a hop is a hop across any resource, not only across topics. The walk follows every relationship it meets, including links to projects, repositories, environments and users, and only filters down to topics at the very end. At depth 2 a topic linked to a project can therefore return every other topic linked to that same project. Depth 3 and above is rarely what anyone intended.

Fields

Comma-separated list of the topic fields you want back, for example mid,title,category_status. Write field names on their own, with no ${} wrapper.

Leave it empty and you get the whole topic document minus the internal search-index blob. That is convenient and expensive: every custom field of every matched topic lands in the stash and stays there for the rest of the rule. On a wide category with a deep search, name the four or five fields you actually read.

Naming fields is exact. mid is not added for you, so a list like title,category gives back records with no mid in them.

Single?

Returns one topic instead of a list, so the Return Key holds a record rather than an array.

Which one is not defined. No ordering is applied to the final lookup, so you get whichever record the database hands back first. Do not read this as "the oldest" or "the lowest mid". Narrow the search with statuses and categories until only one topic can match, then tick this.

When nothing matches, Single? leaves the Return Key empty rather than failing. Test it with IS EMPTY before you use the value.

Do not exclude event mid

By default the op removes the topic that triggered the rule from the results. That is a different value from the Mid field: it is the topic carried by the event that started the rule, which in a workflow or status-change rule is the topic being edited.

Tick this to keep that topic in the results. In rules that are not driven by a topic event there is nothing to exclude, so the checkbox has no visible effect either way.

Mids only?

Returns bare mid strings instead of whole topic records, taking the mid out of each record after Fields has already been applied. The two fields therefore interact: name a Fields list without mid in it and you get back a list with one empty entry per matched topic. Leave Fields empty, or include mid in it, whenever this box is ticked.

Worth ticking whenever you only need to feed the mids into another op such as Change Topic Status. It keeps the stash small, which matters because everything you put there is carried for the rest of the rule and shows up in rule debugging output.

Combined with Single? you get one mid as a plain string.

What lands in the stash

The Return Key on the Options tab names the variable. With Return Key set to related:

Configuration	Value of related
default	list of topic records
Mids only?	list of mid strings
Single?	one topic record, or empty
both	one mid string, or empty

A Return Key of = behaves differently. With Single? ticked, the fields of the topic record are merged into the stash as individual variables, so title and category_status become stash values in their own right and overwrite anything of the same name. Without Single? the result is a list, nothing is merged, and you end up with a stash variable literally named =.

Nothing else is written. The op never changes a topic, never logs a line of its own, and takes no part in rollback: on a rollback pass it runs again exactly as it did going forward, unless you untick Run Rollback on the op's Options tab.

Combining with other ops

Load a list, then walk it with FOR eval and act on each entry. Tick Mids only? so the loop variable is a plain mid you can drop straight into Change Topic Status.

Branch on the result with IF var condition THEN. IS EMPTY on the return key tells you nothing matched, and HAS tells you whether a particular mid is in the list.

Use Get topics that matches conditions when the search is not anchored to one topic, and LOG Message to print what came back while you are still building the rule.

Examples

Collect the changesets under the release that fired the rule, skipping anything already closed.

Mid                        ${topic_mid}
Query type                 children
Filter statuses            Closed, Rejected
Not in statuses            [x]
Depth                      1
Fields                     mid,title
Mids only?                 [ ]

Find the release a changeset belongs to and keep the record for later ops to read.

Mid                        ${topic_mid}
Query type                 parents
Filter categories          Release
Depth                      1
Single?                    [x]
Return Key                 parent_release

Grab the mids of every neighbour in both directions, including the topic that triggered the rule, to feed a bulk status change.

Mid                          ${topic_mid}
Query type                   related
Depth                        1
Do not exclude event mid     [x]
Mids only?                   [x]
Return Key                   affected_mids