Create a new topic

Creates exactly one topic and hands back its mid so later ops can work on it. Use it to open a task or an incident from inside a rule rather than asking a person to fill in the topic form.

The op sets the topic's title, category, status and creating user from named fields, and everything else from a YAML block of field ids. It does not go through the topic form, which means the checks the form performs are not performed here.

Fields¶

Title¶

The topic title. The form will not let you save the op with this empty. It expands ${} placeholders, so ${category.acronym}#${parent_mid} deployment produces a readable title built from the stash.

The title is cleaned before it is stored: HTML tags are stripped, and line breaks become spaces. A title that comes out as nothing but whitespace fails the op with a message that the title is mandatory. A title that comes out completely empty skips that check, and the topic is created with a blank title. A title key in Topic data is ignored, because this field is applied last and wins.

Category¶

Which category the topic belongs to. Required, one value only, and matched against both the category id and the category name. A value that matches neither fails the op with Category <value> does not exist in the system.

The category decides which field ids are accepted in Topic data and which permission is checked. Change the category on an existing rule and the field ids underneath it usually stop matching, which is silent (see Topic data below).

Status¶

The status the new topic starts in. Required, one value only, matched against both the status id and the status name. A value that matches neither fails the op with Status <value> does not exist in the system.

The status is not checked against the category workflow. You can land a new topic directly in a status that no transition leads to, and no warning is raised. That is often what you want for automation, and a good way to strand a topic if it was not.

User¶

The user recorded as having created the topic, and whose permission is checked. Required. The list offers active accounts including system accounts, plus the global variables that hold a user, and you can type a value the list does not offer.

The permission checked is the right to create topics in Category for that user; failing it stops the op with User '<name>' does not have permission to create topics of category '<id>'. If the value never reaches the job at all, which only happens on a hand-edited rule, the job owner is used, falling back to clarive.

Title, Category, Status and User all share one trap: a ${} placeholder that does not resolve is passed through as literal text rather than becoming empty. A misspelled variable in User sends the name ${my_usr} to the permission check, and in Category it produces a does-not-exist failure naming the placeholder itself.

Bypass security?¶

Off by default. When on, the create permission is not checked and the topic is created under the name in User regardless of what that user is allowed to do.

Topic data. Enter field id in Key and string or variable (${variable}) in Value¶

A YAML editor for everything the four named fields above do not cover. One key per field.

Keys are field ids, the identifier attached to the field in the category form, not the label the user reads. Getting one wrong is silent: a key that does not match a field id of Category is dropped, the topic is created without it, and nothing appears in the log. Create a topic, look at what came out, and go back for the keys that did not stick.

Keys are taken literally. A ${} placeholder in the key position is not expanded and will never match a field. Values are a different story: they expand placeholders, and a value that is a single placeholder keeps the type of the variable, so ${my_list} stays a list instead of being flattened into text.

A value is read as YAML, so it can be a plain string or a nested structure:

description: "Raised by ${job_name}"
foo_items: ${changed_objects}
project:
    - ${project_ci.mid}
my_map:
    my_key: "myvalue"

Fields that point at a resource or another topic take mids, not names, and take them as a list even when there is only one. That is the shape the project field and any topic-to-topic link both want.

Five keys are overwritten before the topic is saved and cannot be set here: title, username, category, id_category_status and action. The first four carry the values from the named fields above; the last is used internally to tell a create from an update.

Comments in this editor are discarded when the op is saved, and the editor says so underneath. YAML that does not parse raises a YAML Error dialog and refuses to save the op, so a broken block never reaches a job.

Fields the category marks as mandatory are not enforced. A topic created by a rule can end up missing data that the topic form would have refused to submit without.

What the op returns¶

The new topic's mid, as a plain value. Put a name in the Return Key field on the op's options (see Rule Palette) and the mid is waiting in the stash under that name for every op after it. Without a Return Key the mid is thrown away and you have no handle on the topic you created.

Creation raises the normal new-topic event, so the notification rules and subscriptions that fire for a hand-created topic fire for this one too.

Nothing about this op is undone by a rollback. Worse, the op runs again during a rollback pass by default, which creates a second topic. Clear Run Rollback on the op's options unless you want that, or pair the op with Topic Delete inside IF ROLLBACK.

Combining with other ops¶

Capture the mid with Return Key, then feed it to Change Topic Status to move the topic on, or to Topic Delete to clean it up on the failure path.

SET VAR is handy for building the title or a field value out of several stash pieces before this op runs, which keeps the YAML readable.

To create one topic per item in a list, wrap this op in FOREACH CI and use the loop variable in Title and in the values.

Get topics that matches conditions is the op to reach for when you want to avoid creating a duplicate: look first, branch with IF var condition THEN, create only when nothing came back.

Examples¶

Open a follow-up task from inside a job, keeping the new mid for later.

Title      Analysis task for ${job_name}
Category   Task
Status     To Do
User       clarive
Bypass security?   [x]
Return Key         new_task_mid

Topic data:
    description: "Opened automatically by job ${job_name}"
    parent_topic: ${foo_topic_mid}
    application:
        - ${project_ci.mid}

Record a delivery, with a list field filled from a variable produced earlier in the job.

Title      Delivery ${build_number}
Category   Delivery
Status     Received
User       ${username}
Bypass security?   [ ]
Return Key         delivery_mid

Topic data:
    description: "${objects_count} objects from ${bar_repo}"
    delivered_items: ${baz_objects}
    delivery_type: ${delivery_type}