Latest update: 20.10.2026

Introduction

The Neo Agentic Assistant, which is a MCP-connected agent, reads template and attribute metadata programmatically, primarily through the describe_template call to understand the data model (templates, attributes, relations). That call returns, for every attribute: its code, type, whether it's read-only, its enabled/required rules, its valid values — and two free-text fields you write yourself: Help and Description. If those two fields are empty, generic, or wrong, the agent has nothing to reason from except the raw attribute code and type, and it will guess. On a real data model, a guess is usually wrong: a status value that looks selectable but is actually system-managed, two attributes with the same code that point to different things depending on the template, a reference field whose direction isn't obvious from its name. Writing good Help and Description text is how you close that gap. This article provides guidance for creating good Help and Description texts.

How the M42 Professional Default Agent uses MCP to work with your data model

This diagram shows the loop the M42 Professional Default Agent runs in AI Core every time it's triggered — by a new ticket, a scheduled scan, a user question, or a proposed change.

The agent first decides which MCP tools to call and in what order, always following the same rule: metadata before data. That decision splits into two tracks that run together:

• Learn the data model — the agent calls list_templates / describe_template to ask the MCP server what templates and attributes exist, and whether each one is read-only, required, or enabled. This is where it reads the M42 Professional configuration: the Help text (shown to human users) and the Description text (hidden — written as direct instructions to the agent) that you configure on each template and attribute.
• Act on the data — the agent calls list_datacards / create_datacard / update_datacard to query, filter, create, and update actual records, guided by what it just learned from describe_template. This is where it touches the M42 Professional data: tickets, problems, changes, CIs, knowledge base articles, and their relations to each other.

The agent repeats this loop as needed — another describe_template call, another query, another write — until it decides it has enough to act, then either reports back or updates the record.

This describe-then-act loop is what powers agentic use cases across the platform. The six shown here are examples, not an exhaustive list:

• Change impact analysis — walks CI dependencies outward from a change and ranks what's really likely to be affected, with confirmed fallout outranking merely predicted fallout.
• Problem candidate discovery — spots a real pattern across open tickets (same symptom, same system) and proposes a problem record with root cause and every ticket linked, never created without confirmation.
• CAB-wide change-risk briefing — runs the same blast-radius reasoning across a whole week of changes at once, flagging when two unrelated changes touch the same system in the same window.
• Hidden single point of failure — looks across many services for a shared dependency and ranks it by how many independent services would be affected if it failed.
• Root-cause suggestion from a ticket — works backward from a reported problem to a recent change that plausibly explains it, showing the connection chain so it can be verified.
• Faster answers on one ticket — summarizes for handover, suggests a resolution grounded in a real KB article or past ticket, drafts a customer update, or turns a resolution into a new KB article.

The same loop extends to any use case your own data model supports — the quality of the agent's answers on all of them depends directly on how well your templates and attributes are described, which is exactly what the rest of this article covers.

This is not a copy-paste job

Every customer's data model is different. Template names, attribute codes, status values, hidden/system-managed states, category and service hierarchies, CMDB relation types, and the business rules layered on top of all of it are configured per customer. Descriptions written for one customer's data model will not be correct for another's, and generic text copied from documentation or another instance can actively mislead the agent. Treat every example in this article as an illustration of the pattern to follow, not text to paste into your own configuration unchanged. Before publishing a description, check it against your own live configuration and your own business context — the correct text is the one that matches what your instance actually does. You can use agentic development tools to review your configuration XML file and create draft descriptions and helptexts.

The appendix at the end of this article includes example descriptions and helptexts for a sample of standard templates. Since most modern customer implementations start from that same baseline configuration, it's a genuine starting point — not just an illustration. But it covers only a small fraction of a full data model, and all texts needs to be checked against your own configuration before you trust it. Read the note at the top of the appendix before using it.

Two fields, two audiences

Where a field already has good Help text, leave it. Where it's missing, blank, or copy-pasted from a different template, fix it too — the agent's Description text is often written assuming the Help text next to it is accurate.

What to cover in Description — recurring patterns worth checking for

Across templates, the same handful of situations keep needing explicit agent guidance. Look for these in your own model:

• Same-named fields that mean different things. An attribute with the same name or code can reference different kinds of records depending on the template. State explicitly what it points to on this template if the name is ambiguous.
• Reference direction, and whether it's reciprocal. Say whether a field is a forward reference (you set it) or a backreference (the platform populates it from the other side), which field is its counterpart, and whether linking A to B also creates B to A automatically — many aren't reciprocal, and an agent that checks only one side will miss real relationships.
• Status values that look settable but aren't. A workflow's terminal or hidden state (for example, a "Closed" status reached automatically after time spent in "Resolved") often still appears as a selectable value. Name the value the agent should set instead, and say what happens if it tries to set the hidden one directly.
• Graph/relation traversal fields. If your CMDB or process model has one field that is the complete set of relations and other fields that are pre-filtered subsets of it, say which is which, and give the agent a traversal strategy (starting nodes, hop limit, when to stop) instead of leaving it to explore blindly.
• Read-only / auto-computed fields. Say so explicitly, and point to the field(s) the agent should write instead.
• Write-once or self-clearing fields. Some integration fields are written once and then transformed or cleared by a handler. Explain the lifecycle so the agent doesn't try to read back a value it just wrote.
• Audience-sensitive fields. Internal-only vs. customer-facing comment or note fields must state which audience they reach — this is how you stop an agent leaking internal diagnostic notes into a customer-visible field, or the reverse. Please note that user permissions should primarily be used for limiting the access to data. Neo and the MCP runs always with the user's permissions.
• Fields that are configured but inactive. If a template hides or ignores a field in favor of another, say so and point to the field actually in use.

The appendix below shows real examples of every one of these patterns. Don't reuse the specific field names or values unless your configuration genuinely matches — reuse the shape of the reasoning. Please refer to the MCP server documentation for more settings (e.g. blacklisting templates, classes and attributes). 

Template-level descriptions

Give every template an agent will work with a short description of what kind of record it is, and — more importantly — what it is not: how it differs from the templates it's most easily confused with in your model. An agent choosing which template to search or create against benefits far more from "how do I tell these apart" than from a restatement of the template's name. The appendix includes OOTB examples of this for several templates — but not all of them (there's none below for Change, Problem, Service, or Task, for instance). Templates without an example still need a description; write one using the same pattern.

Priority order

1. Template-level description for every template an agent will touch.
2. Primary classification and status fields, including any hidden/system-managed values.
3. Reference and backreference fields an agent will use to relate records to each other.
4. Relation/traversal fields (CMDB or equivalent), with traversal guidance.
5. Everything else

Before you publish

• Test against your actual configuration — call describe_template, or ask Neo a question that should exercise the field, and confirm the agent behaves the way your Description says it should. A wrong description is worse than a missing one, because the agent trusts it.
• Treat this as living documentation. Revisit descriptions whenever you add an attribute, rename one, add a status value, or change a business rule — stale Description text is a common source of an agent confidently doing the wrong thing.
• Don't put sensitive data, credentials, or internal security details into Description text. It isn't shown to end users, but it is passed into an LLM's context whenever an agent reads that template — treat it as data the model will process, not as a secure hiding place.

Appendix: OOTB example descriptions

What follows is the actual Help and Description text drafted for Efecte's own OOTB reference environment (Neo1), covering a sample of standard templates: Ticket, Problem, Change (plus the CI relation and CI templates used for impact analysis), Knowledge Base Article, and a handful of others. Two things before you use any of it:

• This is a fraction of the model, not the whole thing. The out-of-the-box Ticket template alone has 199 attributes across 19 classes; only the ~28 reference, backreference, and comment-log fields relevant to investigating, triaging, or tracing a ticket are covered below. Problem has 81 attributes across 14 classes, similarly only partially covered. Templates like Change, Service, Task, and any custom templates in your own model have no full coverage here at all. Treat everything below as a worked set of examples and a head start, not a finished configuration — you will need to write descriptions for everything not listed here, using the patterns above.
• Verify every one of these against your own configuration before publishing them. Category lists, status workflows and hidden states, SLA logic, custom attributes, and business rules are exactly the things customers most commonly change from the OOTB baseline. A description that's accurate on a vanilla Neo1 install can become wrong the moment a status value is renamed, a workflow rule changes, or a field is repurposed. A few items below are explicitly flagged as unconfirmed even on Neo1 itself (marked [confirm] or note before publishing) — treat that as the minimum verification bar, not the full list of things to check.

You can influence how the agents behave by modifying the template and attribute descriptions, as described in this article. In addition to that, the MCP server instructions (platform setting mcp.server.instructions can be used to provide universal instructions to the agent). Below is an example:     

Each ESM datacard returned by the tools has a view page at {base}DATACARD_ID, where DATACARD_ID is its dataCardId. You may show a datacard's name as a Markdown link to that page — [NAME]({base}DATACARD_ID) — using only a dataCardId from a tool result.Before calling create_datacard, always call describe_template for the target template and use what it reports:- Set a value only for an attribute that describe_template does not flag with readOnly: true; absence of the flag means you may set it. A flagged attribute is server-managed or not yours to write — omit it.- Supply every attribute that is required and currently enabled.- Leave an attribute unset when its enabledIf condition is not satisfied by the values you are sending; such an attribute is neither persisted nor required.- Pass a reference value as the target datacard's dataCardId, found with list_datacards.- Omit the folder argument and let the default folder apply, unless the datacard genuinely belongs in a specific one from creatableFolders.Before calling update_datacard:- Identify the target datacard by a dataCardId from list_datacards, and read that row's readOnly flag: a row flagged readOnly: true cannot be updated at all, so do not try.- Call describe_template for attribute codes, types and valid values — but not to decide whether an attribute can be updated. Updatability is resolved per datacard: an attribute flagged readOnly: true may still be updatable on this one, and an unflagged one may still refuse the write. Attempt the update and act on the error instead of declining in advance.- Supply values only for the attributes you intend to change, and omit every other one. Omitting an attribute is how you leave it unchanged.- Never send null, an empty string or an empty array. This tool only sets values; emptying an attribute is not something it does, and all three are rejected.- For a multi-value attribute, the array you send is the complete resulting set, not a list of additions: include the values that should stay, or they are removed.- Pass a reference value as the target datacard's dataCardId. Setting a reference may replace or empty the values of the attributes that reference feeds.- If a value you read back afterwards differs from the value you wrote, it is owned by the server's own processing — a save listener, a workflow, or reference-copy configuration. Report what the datacard now holds; do not retry the same update to overturn it, because an identical retry re-triggers the same processing and only repeats its side effects.

Ticket template

The descriptions below covers the reference, backreference, and comment-log fields relevant to investigating, triaging, or tracing a ticket's relationships. Most other attributes need no more than their datatype.

service — Service

Help

Select which service this ticket concerns.

Description

Single reference to service — the classification field actually used for Ticket (see category below, which is hidden). Treat the referenced service as a starting node for CI-relation traversal the same way change_service is on the Change template: read its dependent_services (backreference) and required_services to see what it connects to. Also check this ticket's own all_impacted_services and required_services fields (distinct fields, not the service datacard's) for additional services already recorded as in scope.

category — Category

Not shown — hidden on this template.

Description

Config note on this attribute states: "Hidden with Ticket. Only \"Service\" is used for classification by default." Treat this field as inactive for Ticket — do not use it for classification or filtering, and do not expect it to be populated. Use service instead.

status (class ticket_description) — Status

Description

Backend processing status. "09 - Closed" is a selectable value in this list but is not directly settable by automation/API — it is reached automatically by system rules once a ticket has sat in "07 - Resolved" for a period. Automated updates should set "07 - Resolved"; a direct attempt to set "Closed" is expected to have no effect.

related_configuration_items — Related assets

Help

Record all related configuration items here.

Description

Entry point for a CI-impact walk, not the complete answer — the Ticket equivalent of Change's affected_cis. References application, cloud_infrastructure, database, device, network, and service. Treat each listed CI as a starting node: read its all_ci_relations with select to find CIs one hop further out, then continue breadth-first (dedupe by dataCardId, 3 hops by default, cap ~25-30 tool calls) before answering an impact or root-cause question. Never answer "what does this ticket affect / what's causing this" from this field's contents alone.

all_impacted_services — Possibly affected other services

Help

This field will show all other services that might also be impacted by an issue with the service recorded for this ticket.

Description

Reference to service, multi-value, read permission only. Populated when an incident is suspected or known to affect more than one service. Treat each entry as an additional starting node for impact traversal alongside service and related_configuration_items — do not treat it as exhaustive; it reflects what a human has recorded, not a computed blast radius.

required_services — Required other services

Help

This field shows the services that are required to provide the service recorded for this ticket.

Description

Reference to service, multi-value, read permission only. Upstream/dependency direction: these are services this ticket's service needs to function, not services this ticket impacts. Useful for root-cause reasoning (is the real problem upstream?) but do not list these as impacted by this ticket.

parent_ticket — Parent ticket

Help

If this ticket belongs to a previously recorded parent ticket, then link the parent ticket here.

Description

Single reference to ticket. If populated, this ticket is one of potentially several fanned out from a shared parent (e.g. a mass incident). Follow this reference to find the parent's context; see child_tickets for the inverse direction.

child_tickets — Child tickets

Help

If this is a parent ticket, then the related child tickets will be automatically listed here. You don't need to link the child tickets here. They will be automatically linked when the child ticket is created.

Description

Backreference, auto-populated from other tickets' parent_ticket field — do not write to it. If investigating a suspected mass incident, check here for tickets already fanned out from this one before assuming this is an isolated report.

related_problem — Related problems

Help

Create new or record all related problems here.

Description

Backreference, populated from Problem's related_incident field. Same direction ambiguity as Change's affected_related_incidents: a linked problem may be the root cause of this ticket, or may have been opened because of it. State which direction you're inferring and the evidence (e.g. relative creation dates) rather than presenting it as certain.

related_change — Related changes

Help

Create new or record all related change requests here.

Description

Backreference, populated from Change's affected_related_incidents field (see that field's own entry in the Change template's description doc). If a linked change's implementation date falls shortly before this ticket's creation date, treat the change as a strong root-cause candidate; if after, treat this ticket as a likely trigger for the change instead.

related_standard_change — Related standard changes

Help

Create new or record all related standard changes here.

Description

Backreference, populated from Standard change's source field. Standard changes are pre-approved, low-risk, repeatable changes — a link here is typically the routine change that caused or is otherwise associated with this ticket, not a change under active review.

related_hr_requests — Related HR requests

Help

If this ticket should have been an HR request:
- Create HR Request to transform this ticket into a new HR request. This will transfer the issue to the HR team while preserving all details.

If this ticket originated from an HR request:
- The linked HR Request will appear here, containing the original details submitted by the employee.

The original ticket will remain linked to the new HR request for tracking.

Description

Reference to hrsm_case, multi-value. Signals this ticket's provenance relative to HR Service Management, not a CI or process dependency — use it to explain why a ticket changed ownership between IT and HR, not for impact or root-cause analysis.

related_solution — Related solution

Help

If there is a ready solution in the knowledge base for this ticket, the available solution can be used for solving this ticket. The solution description will be automatically added to the resolution field.

Description

Single reference to knowledge_base_article, populated via a category-based search filter (see attribute's internal query on the config). If present, this is the proposed or applied fix — read it before independently researching a resolution, and note whether its content was actually copied into the resolution field or only suggested.

customer — Customer

Help

Please select here the contact information of the customer who this issue concerns.

Description

Reference to person — the end user this ticket is about. Distinct from requested_for (who the request is being made on behalf of, when different from the reporter) and from support_person/support_group (who is handling the ticket, not affected by it).

requested_for — Requested for

Help

If this request is being made on behalf of someone else, select that person here.

Description

Reference to person. When populated and different from customer, this ticket was raised by one person on behalf of another — treat requested_for, not the ticket creator or customer, as whose access/issue the resolution actually concerns.

support_group — Team

Help

This field records which team is responsible for the processing of the ticket. The value can only be assigned by service desk persons.

Description

Reference to support_group — current owning team. For reassignment history, see support_group_changes and previous_support_groups; this field only holds the current value.

support_person — Assignee

Help

This field records which assignee is assigned to work on the ticket.

Description

Reference to person — current assignee. For reassignment history, see support_person_changes and previous_support_persons; this field only holds the current value.

incident_manager — Incident manager

Help

For major incidents, record the person coordinating the response here.

Description

Reference to person, single-value. Only meaningful when this ticket is classified as a major incident — check whether it's populated before treating this as a major-incident record; an empty value likely means this is a routine ticket, not that no manager is assigned.

incident_team — Team members

Help

List the additional people involved in resolving this major incident.

Description

Reference to person, multi-value. Additional major-incident responders, separate from and additional to the single support_group/support_person fields used on ordinary tickets. Populated together with incident_manager.

customer_vip_sla, organization_sla, service_sla — SLA candidates

Help (per field, substituting the matching label)

Only used when Ticket type = Incident, as a candidate input for SLA resolution.

Description (per field)

Reference to service_level. One of several candidate SLA sources — alongside the self-service category's own SLA — that the SLAFinder handler on sla_used evaluates when Ticket type = Incident. Not necessarily the SLA actually governing this ticket: candidates are not tried in a fixed priority order, the handler picks whichever matching SLA is strictest. Read sla_used for the SLA that actually applies; do not reason about deadlines from this field directly.

sla_used — SLA used

Help

This SLA will be followed to measure the performance against agreed time lines. The SLA is selected based on the service.

Description

Reference to service_level — the SLA actually applied to this ticket. Resolved by the SLAFinderHandler, which evaluates customer_vip_sla, organization_sla, service_sla, and the self-service category's SLA (when Ticket type = Incident) and keeps the strictest match, falling back to a configured default SLA if none apply. Use this field, not the candidate fields, when reasoning about deadlines or breach status.

mcp_comment — Comment from MCP

Not user-facing — written by the MCP/agent integration, not filled in on the form.

Description

Write path for an agent's own diagnostic notes on this ticket — the only field an agent should write to for that purpose. A text field with an ExpressionHandler: whatever is written here is read, appended to internal_comments as a formatted comment (via CommentUtil.createComment, attributed to "Neo"), and this field is then cleared automatically. Write once per note; do not read it back afterward — it will already be empty.

internal_comments — Internal comments

Help

Record here all diagnostic activities that were undertaken to solve the ticket.

Description

Comment-log field (CommentHandler), not a datacard reference — an append-only internal history, agent- and technician-facing only. Existing config note: "MCP / AI should not add value directly into this attribute." Treat as read-only from the agent's side: surface its contents when investigating a ticket, but write new diagnostic notes through mcp_comment instead — never set this field directly.

comment_ess2 — External comments

Help

Remarks/comments to be made for the requester shall be documented here.

Description

Comment-log field (CommentHandler), customer-facing via Self-Service — the opposite audience from internal_comments. Anything written here is visible to the customer; do not put internal diagnostic detail in this field.

status_changes — Status changes

Help

Logging status changes of ticket.

Description

Reference to ValueChange, multi-value, auto-populated — read-only history, do not write to it. Use to reconstruct when status transitions happened, e.g. when checking for SLA breaches or stalled tickets.

support_person_changes — Assignee history / previous_support_persons — Previous assignees

Help (per field)

Auto-populated history of assignee changes on this ticket.

Description (per field)

Auto-populated, read-only. support_person_changes references ValueChange (the change events); previous_support_persons references person (the prior values themselves). Use together to reconstruct handoff timing when investigating delays.

support_group_changes — Team history / previous_support_groups — Previous teams

Help (per field)

Auto-populated history of team reassignments on this ticket.

Description (per field)

Auto-populated, read-only. support_group_changes references ValueChange (the change events); previous_support_groups references support_group (the prior values themselves). Use together to reconstruct handoff timing when investigating delays.

workflow_history — Workflow history

Help

Auto-populated log of this ticket's workflow transitions.

Description

Reference to ValueChange, multi-value, auto-populated — read-only. Broader than status_changes; use when reconstructing the full processing timeline rather than status alone.

link_approval — Approvals

Help

If this ticket requires approval, the approval record will appear here.

Description

Backreference, populated from Approval's ApprovedIssue field — auto-populated once an approval workflow creates an approval record for this ticket. Read-only from here; a ticket with no value here has not (yet) entered an approval workflow.

Problem template

81 attributes across 14 classes; below covers the reference/backreference fields relevant to an agent doing root-cause or impact analysis on a problem. Two items below flag a real discrepancy found while checking a live configuration against the assumptions here — verify before reusing those two.

category — Category

Help

Select the category this problem belongs to. Determines which services are selectable below.

Description

Reference to category. Unlike Ticket (where category is hidden and unused), category is the active primary classifier on Problem — service below is filtered to only options whose related_category matches this field's value. Set category before expecting a meaningful service list.

service — Service

Help

Select which service this problem affects. Only services matching the selected category are shown.

Description

Single reference to service, filtered by category (only services whose related_category equals this problem's category are selectable). Treat as a CI-graph starting node for impact analysis the same way as on Change/Ticket: read its dependent_services (backreference) and required_services to see what it connects to.

status — Status (note before publishing)

Help

Processing status of the problem.

Description

Config marks "07 - Closed" as a hidden/system-managed state via DatacardHiddenStateHandler, not directly settable by automation — set "06 - Resolved" instead and expect closure to happen automatically, matching the pattern on Ticket (07 → 09 - Closed) and HR Request (05 → 06 - Closed). The handler's config also names a second hidden value, "99 - Cancelled", but this template's actual static value is "09 - Cancelled" — that mismatch means the hidden-state rule may not be reliably applying to Cancelled; verify live before assuming "09 - Cancelled" is (or isn't) agent-settable.

related_configuration_items — Related assets (fix before publishing)

Help

Record here the configuration items affected by this problem.

Current live Help text on the reference instance was copy-pasted from the Change template — it literally read "...affected by the change request." Replace it; the text above is the corrected version.

Description

Entry point for a CI-impact walk, not the complete answer — same pattern as Change's affected_cis and Ticket's related_configuration_items. References application, cloud_infrastructure, database, device, network, and service. Treat each listed CI as a starting node: read its all_ci_relations with select to find CIs one hop further out, then continue breadth-first (dedupe by dataCardId, 3 hops by default, cap ~25-30 tool calls). Distinct from root_cause_ci below (a single confirmed answer) — this field is the broader candidate set, not a confirmed root cause.

root_cause_ci — Root cause CI

Help

Once identified, record the single configuration item confirmed as the root cause here.

Description

Single reference (application, cloud_infrastructure, database, device, network, or service) — the confirmed root cause, distinct from the broader candidate set in related_configuration_items. An empty value means root cause hasn't been narrowed to a specific CI yet, not that no CI is involved.

related_incident — Related incidents

Help

Record the ticket(s) that reported this problem.

Description

Forward reference to ticket, multi-value. This is the field that populates Ticket's related_problem backreference — see that field's entry in the Ticket template's description doc for the read side. Direction here is fixed (this problem → the tickets that reported it), but still confirm via ticket creation dates that a linked ticket actually reported this problem rather than being a downstream consequence of it.

changes_that_caused_this_problem — Root cause changes

Help

The Change records linked to this Problem as potential causes. Use this to track Changes that may have contributed to the issue.

Description

Forward reference to change and standard_change, multi-value. Populates Change's resulting_problems backreference — the two are the same relationship viewed from each side. Distinct from required_changes below, which is the opposite relationship (changes raised to fix this problem, not changes suspected of causing it) — do not conflate the two when answering a root-cause question.

required_changes — Required changes

Help

Select changes required to resolve the root cause of the problem or create a new change.

Description

Backreference, populated from Change's (or Standard change's) affected_related_problems field — the change(s) that name this problem as their initiating cause, i.e. changes raised to fix this problem. See changes_that_caused_this_problem above for the unrelated, opposite-direction link.

related_problems — Related problems

Help

Record all related problems.

Description

Forward reference to problem, multi-value, self-referencing. Not guaranteed reciprocal — see referring_problems for the inverse direction; check both when walking problem-to-problem relations.

referring_problems — Referring problems

Help

Other problems that have linked this problem as related.

Description

Backreference, the inverse of related_problems. A problem can appear here without this problem listing it back in related_problems. Always check both fields when walking problem-to-problem relations — checking only related_problems misses edges recorded from the other side.

related_workaround — Related workaround

Help

Link a Knowledge Article that provides a workaround for the identified problem or create a new one.

- Select an Existing Article: Browse and attach a relevant Knowledge Article that offers a temporary workaround to mitigate the problem's impact.
- Create a New Article: Develop a new Knowledge Article if the workaround is new, ensuring it is accessible for others dealing with similar issues in the future.

Description

Single reference to knowledge_base_article — a temporary mitigation, not a permanent fix. Distinct from related_solution below; a problem can have a workaround published while the underlying root cause is still open.

related_solution — Related solution

Help

Link a Knowledge Article that resolves the identified problem or create a new solution.

- Select an Existing Article: Browse and attach a relevant Knowledge Article to provide a ready-made solution.
- Create a New Article: Develop a fresh Knowledge Article if the solution is new, ensuring others benefit from it in the future.

Description

Single reference to knowledge_base_article — the permanent fix for this problem, once found. Distinct from related_workaround above (temporary mitigation only); check whether this field is populated before assuming a problem with only a linked workaround is otherwise unresolved.

problem_manager — Problem manager

Help

The person accountable for driving this problem to resolution.

Description

Reference to person, single-value — the accountable owner. Distinct from support_group below (the working team) and primary_contacts below (stakeholders kept informed, not necessarily working the problem).

support_group — Assigned problem team (note)

Help

Select the team members who will be responsible for investigating and resolving this problem.

Description

Reference to person, multi-value. Despite the attribute code support_group, this references individual people directly, not the support_group template — unlike Ticket's field of the same code, which references a support_group record. Do not expect a single team entity here; expect a list of individuals. (Contrast with affected_teams below, which does reference the support_group template.)

primary_contacts — Primary contacts

Help

Key contacts who are informed by email notifications about the progress of solving the problem.

Description

Reference to person, multi-value — people kept informed of progress, not necessarily people working the problem (see support_group / problem_manager for that) or people affected by it (see affected_users below). See primary_contacts_notification_language for how they're addressed.

primary_contacts_notification_language — Notification language

Help

Select the preferred language for e-mail notifications to ensure clear and effective communication with primary contacts. Choose the language based on the majority preference of the contacts involved.

Description

Reference to language, single-value — controls the language of progress-update e-mails sent to primary_contacts. Not itself a contact or stakeholder field.

affected_organizations — Affected organizations

Help

If the problem is organization-wide, select impacted organizations (such as external organizations or vendors).

Description

Reference to company, multi-value. One of five parallel impact-scope fields (see also affected_departments / affected_locations / affected_teams / affected_users, and the auto-computed impacted_parties below) — populate whichever dimension(s) actually apply; a problem doesn't need entries in all five.

affected_departments — Affected departments

Help

Select departments if the problem affects only specific departments.

Description

Reference to cost_center, multi-value — despite the name, this targets cost-center records, not a dedicated department template. One of five parallel impact-scope fields; see affected_organizations above for the pattern.

affected_locations — Affected locations

Help

Select locations if the problem only affects certain locations.

Description

Reference to location, multi-value. One of five parallel impact-scope fields; see affected_organizations above for the pattern.

affected_teams — Affected teams

Help

Select teams if the problem only affects the team level.

Description

Reference to support_group, multi-value — this one does reference the support_group template (contrast with this template's own support_group field above, which references people, not support_group records). One of five parallel impact-scope fields; see affected_organizations above for the pattern.

affected_users — Affected users

Help

Select users if the problem only affects certain users.

Description

Reference to person, multi-value — the actual end users impacted, distinct from primary_contacts (people being notified) and support_group (people working the problem). One of five parallel impact-scope fields; see affected_organizations above for the pattern.

impacted_parties — All impacted parties

Help

Shows all impacted parties where problem affects.

Description

Auto-computed, read-only rollup (ExpressionHandler) that concatenates names from affected_organizations, affected_departments, and the other impact-scope fields into a single display list. Do not write to it directly — populate the individual affected_* fields instead; this field updates itself.

process_tasks — Process tasks

Help

Process tasks are created to guide the Problem Manager through each phase of the problem lifecycle.

Description

Backreference to WorkflowTaskInformation (via its wf_issue field), auto-populated by the problem-management workflow — read-only from here, do not create entries directly. Distinct from tasks below (ad hoc investigation tasks a person creates manually).

tasks — Tasks

Help

Create and manage tasks needed to investigate and resolve the problem. Assign tasks to appropriate teams or individuals.

Description

Forward reference to task, multi-value — ad hoc tasks created directly on this problem, distinct from process_tasks above (system-generated workflow-phase tasks).

workflow_history — Workflow history

Help

Auto-populated log of this problem's workflow transitions.

Description

Reference to ValueChange, multi-value, auto-populated — read-only. Use to reconstruct the processing timeline when investigating delays.

Change template

Fields marked [confirm] below rely on a reading of naming conventions rather than anything explicit in the configuration — verify the actual meaning before reusing those.

affected_cis — Affected CIs

Help

Record here the configuration items that will be affected by the change request.

Description

Entry point for a change-impact / blast-radius walk, not the complete answer. Treat each listed CI as a starting node: for each one, read its all_ci_relations with select to find CIs one hop further out, then continue breadth-first (dedupe by dataCardId, 3 hops by default, cap ~25-30 tool calls) before answering an impact question. Never answer "what does this change affect" from this field's contents alone.

change_service — Service

Help

Select here to which service this change is being made.

Description

Single reference to service. Treat the referenced service as another starting node for impact analysis: read its dependent_services (backreference) to find what depends on it, and required_services to find what it depends on. A change to this service can propagate in both directions, not just downstream.

change_category — Category

Help

Select which category this change belongs to.

Description

Reference to category, used for classification and reporting only. It is not part of the CI relation graph — do not treat it as an edge when walking impact or root cause.

affected_related_incidents — Affected / related incidents

Help

Record any incidents connected to this change here.

Description

Reference to ticket, multi-value. This field does not distinguish direction: it may hold incidents that prompted this change (root-cause direction) or incidents raised because this change caused disruption (impact direction). When citing one of these in an answer, state which direction you're inferring and the evidence for it (e.g. the ticket's creation date relative to this change's implementation dates), rather than presenting the direction as certain.

affected_related_problems — Initiating problems

Help

The Problem record that initiated this Change. Use this to trace back to the root cause being addressed.

Description

Points backward: the problem that caused this change to be raised. In a root-cause walk that arrives at this change, follow this reference to continue one hop further back toward the original problem.

resulting_problems — Resulting problems

Help

The Problem record created to investigate or address an issue caused by this Change.

Description

Backreference, populated when a problem names this change as its cause. Points forward. If asked for this change's impact, check here first: a problem already linked here is a confirmed outcome and outranks anything inferred from affected_cis, which is only a prediction of what might be affected.

related_changes — Related changes

Help

Record other related change requests here.

Description

Reference to change, multi-value. Not guaranteed reciprocal — see referring_changes for the inverse direction; check both when walking change-to-change relations. When assessing risk or investigating an incident, a change listed here that also touches the same CI(s) as this one, in a similar time window, is a stronger root-cause candidate than either signal alone — rank it accordingly.

referring_changes — Referring changes

Help

Other changes that have linked this change as related.

Description

Backreference, the inverse of related_changes. A change can appear here without this change listing it back in related_changes. Always check both fields when walking change-to-change relations — checking only related_changes misses edges recorded from the other side.

ci_relation template

relation_type — Relation type

Help

Depends on — the source needs the target to function.
Runs on — the source executes on top of the target.
Hosted on — the source is hosted by the target.
Connects to — the source has a network or integration connection to the target.
Contains — the source is composed of, or includes, the target.
Related — a general association that doesn't fit the types above.
Normal — default/unspecified.

Description

How to weight this edge when ranking impact or root-cause candidates: depends_on, runs_on and hosted_on mean disruption to the target very likely propagates to the source — weight these highest. connects_to is a network/integration link — disruption may propagate depending on how critical the integration is; do not assume it always does. contains means the source is composed of the target. related is a weak, unspecified association — weight it lowest. normal: [confirm actual meaning before relying on it for ranking].

source_ci_ref — Source CI

Help

The configuration item this relation originates from.

Description

Backreference, populated from the originating CI's own record. If you reached this ci_relation by following a CI's ci_relations or all_ci_relations field, this is where you came from — no need to query it again to go "back".

target_ci_ref — Target CI

Help

The other configuration item in this relationship.

Description

The far end of this edge, in the direction relation_type names. This dataCardId is where the walk continues one hop further: resolve its template against the reference's target list (application, cloud_infrastructure, database, device, network, saas_component) if not already known, then read that CI's own all_ci_relations to keep going.

CI templates — application, network, database, cloud_infrastructure, saas_component, device

Same attributes, identical text on all six templates.

all_ci_relations — All CI relations

Help

Shows all relationships where this CI is either a source or target.

Description

The complete edge set for this CI — use this field for traversal, not the individual cmdb_* fields, unless you specifically need only one relation type. Always pass select naming this attribute; without it list_datacards returns only id and name, and there is nothing to traverse. Each value returned is a ci_relation dataCardId, which is an edge, not a destination — resolve it one hop further by reading its relation_type and target_ci_ref (or source_ci_ref, if this CI is the target) to reach the actual related CI.

ci_relations — CI relations [confirm before publishing]

Help

Relations recorded directly from this CI's own record.

Description

[confirm] Believed to be the source-only subset of all_ci_relations — relations recorded directly on this CI, as opposed to ones recorded only from the other CI's side. If confirmed, prefer all_ci_relations for traversal so relations recorded from the other side aren't missed.

cmdb_connects_to, cmdb_contains, cmdb_related, cmdb_runs_on, cmdb_depends_on, cmdb_hosted_on — relation-type subsets

Help (per field, substituting the matching label)

Relations of type "<Connects to / Contains / Related / Runs on / Depends on / Hosted on>", shown in the Visual Analyzer.

Description (per field, substituting the matching relation_type code)

Pre-filtered subset of all_ci_relations where relation_type = "<connects_to / contains / related / runs_on / depends_on / hosted_on>". Use only when you specifically need just this relation type; for a general impact or root-cause walk use all_ci_relations instead so other relation types aren't missed.

cmdb_normal — Normal (relations) [confirm before publishing]

Meaning of the "Normal" relation type is unclear from the configuration — get the intended meaning confirmed before writing text for this one on your own instance. Placeholder only:

Help

Relations of type "Normal", shown in the Visual Analyzer.

Description

Pre-filtered subset of all_ci_relations where relation_type = "normal". [confirm] Meaning of this relation type is not established — do not use it to weight impact ranking until confirmed; treat entries here the same as "related" (lowest weight) in the meantime.

Knowledge Base Article template

Covers only the attributes referenced by a proactive knowledge-gap-scanning agent flow, not necessarily every attribute on a real template — verify attribute codes against describe_template before reusing.

solution_name — Title

Help

The article's title. Make it specific enough that someone searching by symptom would recognize it.

Description

Primary search-facing field: this is what a coverage check filters against first (solution_name CONTAINS '<term>' OR solution_keywords CONTAINS '<term>') before creating a new article. Keep titles specific and symptom-based, not generic — "VPN connection drops after Windows 11 update", not "VPN issue". A vague title here is the most common reason a real duplicate slips past a later coverage check.

solution_keywords — Keywords

Help

Comma-separated search terms — error text, affected system/product names, category or service.

Description

Secondary search-facing field, matched alongside solution_name during coverage checks. When drafting: 4-8 comma-separated terms from the ticket's (or cluster's) subject, category/service, and error text in details. When checking for existing coverage: a match here or in solution_name is a candidate, not confirmation — read the candidate's solution_description before deciding it actually covers the same symptom and resolution; title/keyword overlap alone is not enough (an article about "VPN setup" does not cover "VPN disconnects after Windows update" just because both mention VPN).

solution_description — Content

Help

The article body: what the user experienced, why (if known), how it was fixed, and any caveats.

Description

HTML body, structured as <h2>Symptom</h2> / <h2>Cause</h2> / <h2>Resolution</h2> / <h2>Notes</h2>. Cause and Notes are optional — omit the section entirely rather than leaving it empty. Resolution is a numbered list, paraphrased from the source ticket(s)' resolution field — never copied verbatim. This is the field a coverage check must actually read before concluding an existing article covers a new candidate; a title/keyword match is only ever a reason to look here, not a substitute for it.

knowledge_type — Knowledge type

Help

Resolution — a known fix (most common).
How-to — a procedure or set of instructions.
Configuration knowledge — setup or settings.
General knowledge — informational, no specific fix.

Description

Classification only — not part of any search filter or traversal, and not used by the coverage check. Choose based on what the resolution content actually is (a fix, a procedure, a settings change, or pure information), not from the ticket's category or template.

status — Status

Help

Workflow status. New articles created by an agent start at "01 - New" for review.

Description

An agent creating this article must set exactly "01 - New" and never anything further along the workflow — publishing is a human knowledge-manager decision. Never update this field on an existing article found during a coverage check; a matched article's status is not this agent's to change, whatever it currently is.

published_in_self_service — Published in self-service

Help

Yes / No — whether end users can find this in self-service search, once published.

Description

Defaults to "No" on a draft an agent creates. Only set "Yes" if the content contains no internal-tooling references and no tenant/instance-specific steps that would confuse or mislead an end user reading it without support-agent context. This is a drafting-time judgment call, not something to leave to the eventual human publish step to correct.

kba_based_on_tickets — Based on tickets

Help

The ticket(s) this article was written from — kept for traceability back to the source.

Description

Multi-value reference to ticket. Set only at creation time, by the agent drafting the article: a single ticket's dataCardId for a per-ticket detection run, or every ticket in the qualifying cluster for a batch/scan run — not just the subset sampled for drafting content. Never updated afterward. If a later run finds more tickets matching an already-existing article, that's a signal for human review, not a reason to append to this list unattended.

consolidated_resolution — Consolidated resolution

Help

A short plain-text summary of the fix — for scanning a review queue without opening the full article.

Description

Plain text, a couple of sentences, not a repeat of solution_description's HTML. State the actual fix in one place a reviewer can read without opening the article body. If drafted from multiple tickets that resolved differently, say so briefly (e.g. "most resolved by X; two also required Y") rather than presenting one resolution as if it were universal.

identified_and_skipped_clusters — Identified and skipped clusters

Help

For batch detection runs: other patterns found in the same run that weren't turned into an article, and why.

Description

Plain text, one line per skipped candidate with a short reason, e.g. "VPN / Remote Access, 2 tickets — skipped: no substantive resolution", "SharePoint / Access, 4 tickets — skipped: duplicate of existing KBA 'Access issues after role change'". Only meaningful for a run that evaluates many candidates at once (a scheduled batch/gap-scan run) — a single-ticket detection run has nothing else to report and should leave this empty, or write "N/A — single-ticket evaluation" if the field is required. Set this on every create_datacard call within the same run, not just the first, so a run that creates several articles doesn't lose track of what else it found.

Other template-level descriptions

These are template-level descriptions (the single description field returned for the template itself via describe_template, distinct from the per-attribute Help/Description pairs above).

announcement — Service announcement

Broadcasts a current operational notice to end users — an active incident, planned maintenance, or a temporary side-effect of a rollout (e.g. a BIOS update temporarily tripping device compliance checks). Distinct from a ticket (something a specific user reported, through any channel) and a knowledge article (a written how-to): check this first when diagnosing a reported problem, before troubleshooting steps or opening a ticket.

ticket — Ticket

A record of something an end user reported or requested — an issue, question, or request for action — however it reached the service desk (self-service, email, phone, or logged manually by an agent). Tracked from creation through resolution by IT/service desk.

hrsm_case — HR Request

A request or case handled by HR (e.g. onboarding, offboarding, an HR-related question) — raised by an employee via self-service, or logged by an HR agent from another channel such as email or phone. Can be linked to an IT ticket when a request needs both HR and IT action — see the Relations section on this template for how that link works.

Attribute status (class HRSM_case_description) — Description

Backend processing status. "06 - Closed" is a selectable value in this list but is not directly settable by automation/API — it is reached automatically by system rules once a request has sat in "05 - Resolved" for a period. Automated updates should set "05 - Resolved"; a direct attempt to set "Closed" is expected to have no effect.

device — Device

An asset record for a specific piece of hardware (laptop, phone, etc.) assigned to a person. Compliance/management state is tracked per integration source rather than one unified field — see the status attribute for this record's own lifecycle state, and intune_compliancestate for Intune-managed device compliance specifically, the field behind "device not compliant" messages.

Attribute status (class device_information_march_2023) — Help

This device's own lifecycle status: Planning, Under construction, In verification, In use, In maintenance, Waiting for disposal, or Disposed.

Attribute status — Description

Separate from the integration-specific sync status fields elsewhere on this template (Intune, SCCM, Raynet, M42 Enterprise) and from intune_compliancestate (security compliance, not lifecycle stage). Use this field for "is this device active / in use / retired" questions.

Attribute intune_compliancestate (class intune_information_march_2023) — Help

Compliance state of this device as evaluated by Intune (e.g. Compliant, Noncompliant, Unknown, Conflict, InGracePeriod).

Attribute intune_compliancestate — Description

This is the field a "your device needs to meet security requirements" self-service message reflects.

knowledge_base_article — Knowledge article

A published how-to or explanatory article for end users. Distinct from a ticket (something a specific user reported) and an announcement (a broadcast operational notice) — check this when a user's question matches a documented topic rather than an active incident. An article is only actually visible to end users in self-service when both an article category is set (knowledge_article_category) and published_in_self_service = "Yes" — treat an article missing either as backend data only, not something to reference, recommend, or link to for this user.

network — Network

A logical network/site definition used for CMDB relationship mapping (which systems sit on which network) — not itself a record of a connectivity incident. A reported VPN/network problem is more likely tracked as a ticket or announcement that references this record, not something to search directly for a root cause.

network_information — Network information

Technical network configuration (IP, subnet, gateway, MAC) attached to a specific device's network interface. Reference data, not an incident source.

notification — Notification

An outgoing message record (subject/message/recipients) generated by the system for a specific event/recipient. Not a source of current operational status the way an announcement is — do not search this when checking for a known active cause.

device_model — Device model

Reference/catalog data describing a model of hardware (make, manufacturer, specs) — not an individual device belonging to a specific user. Useful for what a model supports in general, not for diagnosing one user's specific device issue.

service_item — Self-Service item

A catalog item that can be ordered — equipment, access, or a service — via self-service or by an agent on the requester's behalf through another channel. Distinct from a service (an ongoing operational capability) and a ticket (a reported issue).

Custom fields example: auto-resolution agent flow

These two fields are not part of a vanilla OOTB Ticket template — they're custom attributes added to support a specific auto-resolution agent capability. They're included here as an example of the same Help/Description discipline applied to a custom field, not as something to expect already on your Ticket template.

email_body_neo

Help

The resolution email sent to the customer, generated automatically when this ticket was resolved by Neo.

Description

Write the full customer-facing resolution email body here only when auto-resolving a ticket — populating this field is what sends the email to the customer, and that cannot be undone once written. Only write it after you have reached the resolve bar: a specific, close match from a knowledge base article or a past ticket's actual resolution, not a generic or partial one. Write in the requester's interface language, in plain customer-facing language — no field codes, ids, internal mechanics, or data-model vocabulary ("this request", not "this ticket record" or "datacard"). State the resolution itself; do not add meta-commentary like "this ticket was processed automatically". Never populate this field on the escalation path — an escalated ticket gets no customer email from you; use auto_resolution_summary for the internal record instead.

auto_resolution_summary

Help

A short summary of the automatic investigation and resolution/escalation performed on this ticket.

Description

Write a concise summary here every time you finish processing a ticket, regardless of outcome: what you found (matching KBA, past ticket, problem, or change — or the lack of one), what you changed on the ticket (category, service, linked assets), and whether you resolved or escalated it and why. This is the audit trail for this run and what the calling agent relays onward — write it last, after every other write has already succeeded, so it reflects what actually happened rather than what you intended to do. Keep it factual and short enough that someone can understand the outcome without re-reading the whole ticket. Never put customer-facing resolution language here — this field is not shown to the customer; that belongs in email_body_neo.