Help Desk and tickets

An e-mail alert tells a person. A ticket lands in the queue of the team that fixes the problem, with a number, a deadline and a history. CMS opens that ticket on its own when an alert fires, in the service tool the company already uses — and it also lets any authorised person open one from a failed message, already filled in with the integration’s context.

CMS only opens the ticket. It does not comment on it, close it or read it back: the lifecycle belongs to the service tool. The ticket number is kept in CMS, alongside the message that opened it.

How the pieces fit together

There are three records, created in this order:

1. The tool — under Settings › Parameters › Help Desk. Activating it creates everything sending needs: the tool’s Application, the Interface, the Delivery, the Transformer and the Credential.
2. The destination — under Integration Config › ITSM Configuration. It is the to whom inside the tool: the service group, the category, the urgency. The same tool usually has several destinations, one per area.
3. The alert — under Alerts, the Open a ticket in field picks the destinations for each alert configuration.

Underneath, opening a ticket is delivering a message: CMS builds the body, puts it on the tool’s Delivery, and the message follows the same path as any other — retries, log, Messages screen. There is no special connector per tool, and that is why the ticket’s message shows up in Messages as proof that it went out.

Supported tools

Each tool lists, in the activation popup, the prerequisites on its side — the itil role in ServiceNow, the API turned on in GLPI, the API token instead of the password in Jira. It is worth reading before filling anything in: most first-setup failures are right there.

1. Activate the tool

Settings › Parameters › Help Desk tab.

The Activate button opens the catalogue. Each tool shows up with a description of what it opens, and once you pick one the popup asks for:

The What the activation creates block shows, before you confirm, the Interface and the Delivery that will exist. The choice between Channel and Queue deserves attention:

• Channel (recommended): a ticket rejected by the tool does not hold up the next ones. Tickets have no order among themselves, so this is the right behaviour in most cases.
• Queue: one ticket at a time, in arrival order. If one is rejected, the next ones wait until someone unblocks the Interface — right when the tool is having trouble.

The names created are in English and derive from the acronym: the Interface GLPI_TICKET, the Delivery GLPI_TICKET_OPEN, the Transformer “GLPI GLPI - ticket body” and the Credential “GLPI — CMS integration”. English names are the standard for everything the activation records; the screen texts stay in each user’s language.

The same tool can be activated more than once — a production GLPI and a QA one, for example. Each activation is its own Application, with its own acronym, and so its own names (GLPIQA_TICKET, GLPIQA_TICKET_OPEN). If any of the names already exists, the activation refuses and says which one: it never reuses another activation’s Interface or Delivery.

The Interface and the Delivery come from the tool’s pack, and only the activation installs that pack. The ticket packs do not show up in the Applications pack assistant: installed on a plant Application, they would become a stray ticket Delivery, with no Destination and outside this catalog.

SAP PM

SAP PM is different from the other tools: it does not create an Application. The activation asks for the SAP Application where notifications will be opened — the combo only lists Applications of type SAP RFC/BAPI — and that choice can be changed later, when editing. SAP PM can also be activated more than once, one per SAP Application.

Instead of “What the activation creates”, the screen shows the Delivery that opens the notification in that Application: the SAP RFC Delivery that calls BAPI_ALM_NOTIF_CREATE, found by the function (its code can be anything). The SAP PM pack ships that Delivery ready. For the notification to really exist, three things must be in place on it:

1. BAPI_ALM_NOTIF_SAVE under “Call next, in the same session”. The create BAPI only keeps the notification in the RFC session’s memory; without the save in the same session, the notification vanishes when the connection closes. See follow-up calls.
2. Commit on — the BAPI_TRANSACTION_COMMIT, in the same session.
3. The Interface’s scheduler on, in Schedulers. When it is off, the notification enters the queue and stays there, and “Open ticket” shows “waiting” forever.

The activation and Test connection check all three and say what is missing — the activation refuses while anything is missing.

The grid

The row actions are Details (the Application, Interface, Delivery and Credential that were created), the Body template — green when the tool already has one registered — and edit, which is where Test connection lives.

Deactivating a tool only stops new tickets. Destinations, Interface, Delivery and the ticket history stay intact, and reactivating brings everything back as it was.

Test connection

The button, in the tool’s edit popup, performs a real read on it — without opening a ticket — using the Delivery’s Credential. The result has three states:

• Green: the tool accepted the credential and the read.
• Red: with the reason. 401 means user or password rejected; 403 means the credential was accepted without the permission that opening a ticket requires, and the screen says which one (the itil role in ServiceNow, API access on the GLPI profile).
• Warning: the tool has no read in CMS that confirms the credential (that is the case for InvGate). The test passes with a “not verified” note — the first ticket is what confirms it.

In SAP PM the test is different: it checks the Delivery that opens the notification, the save in the same session, the commit and the Interface’s scheduler — see SAP PM.

Body template

Each tool has a body template: the ticket’s JSON (or XML) in the format that API expects, with the alert fields in place of the values. It is edited here, with the fields panel next to the editor, and it has two roles:

• It is the starting point for every new destination of this tool — except in SAP PM, where the body starts from the Delivery Definition fields.
• It is the body sent by a destination that has no body of its own.

The editor opens with a sample from the tool only as a starting point — Use the tool original template restores it. The sample is never sent on its own: with no saved template and no body on the destination, the ticket does not go out, and the history records the failure.

2. Configure the destination — /ticket-destinations

Integration Config › ITSM Configuration.

A destination answers where, inside the tool, the ticket goes. The typical case is the same GLPI with one destination for Electrical Maintenance and another for IT — the group, the category and the urgency change.

The grid groups destinations by tool: each group header shows the Help Desk, the connection badge (which opens the details) and how many configurations it has. Each row is one configuration, on a single line:

The arrow at the start of the row opens the detail: each Application with its connection, its own reasons, whether it uses the default body or a body of its own and when it last opened a ticket. That is where “which reason makes MES open a ticket?” gets answered — the row’s column merges the reasons of every Application and does not say which is whose.

The Application, Interface, Definition and Reason filters apply per Application: “MES + Application Offline” only shows the destination if MES itself opens a ticket for Offline. With any of them on, rows open with the detail already showing, and Applications outside the filter appear dimmed at the end — the destination still serves them, and whoever is about to change it needs to see that. The text search also finds a reason by name (“offline”).

The actions column holds Opened tickets, edit and delete.

The form

Tool, Name and Delivery are required, and the error shows up on the field itself. Saving does not close the form: the screen confirms it saved and asks whether you want to keep editing or close.

The body. A new destination opens with the Help Desk tab template. When you edit a destination, the editor shows the body that was saved — the template only comes back through the Use the Help Desk tab template button, which asks for confirmation when there is already text in the editor. Nothing is stored until Save.

In SAP PM the starting point is different. The notification goes through no Transformer: the Delivery takes a JSON with its own input fields (descricao, equipamento, localInstalacao, prioridade…). So the body opens with the fields of the chosen Delivery Definition and follows when the Definition changes — an SAP Application has several Deliveries, each with its own fields. Fill the values with the alert fields; the Use the Delivery Definition fields button brings them back. A template registered in the Help Desk tab is still available through its own button.

Body per Application

The same destination often serves several Applications, and the body is not always the same — the SAP PM equipment, the ServiceNow CI. Above the editor sit the Default tab and one per Application: an Application’s body applies to its alerts, and the others use Default. In the new-tab combo, the Applications that already use the destination come first.

On an Application’s tab, the side panel also shows that Application’s Variables, besides the alert fields. Deleting the tab sends the Application back to Default.

Clicking a field in the side panel writes the {{field}} where the cursor is. The panel is as tall as the editor and scrolls on its own when there are many variables.

Three rules apply to the body:

• Write the fields inside the quotes: "name": "{{alertaMensagem}}". The value goes in escaped for the Delivery’s format (JSON or XML) — a quote or a line break in the alert message does not break the ticket.
• JSON is checked on save, with the fields swapped for a neutral value. A stray comma shows up now, not on the first ticket.
• Variables work in the values: {{SNOW_GRUPO}} from a Global Variable, or from an Application Variable with the same name, resolved against the Application that fired the alert. That is how the same destination carries the right CI for each Application.

A minimal body for GLPI:

{
  "input": {
    "name": "{{alertaMensagem}}",
    "content": "{{alertaDetalhe}}\n\nApplication: {{aplicacao}} | Type: {{alertaTipo}}\nError: {{alertaErro}}",
    "urgency": 4,
    "type": 1
  }
}

Body fields

The optional Transformer

Without a Transformer, the body goes out as it is — that is the normal path. The Transformer is for when the ticket needs a rule: urgency depending on the alert type, group depending on the error text. It receives the body with the fields already resolved and returns the final body.

The combo lists the Global Transformers and those scoped to this Delivery. The Delivery’s own (installed by the tool pack) comes first, and it expects a different format: the contract fields (titulo, descricao, urgencia…), not the tool’s JSON. When you pick it, the screen says which fields it expects and offers Use this Transformer input format, which rewrites the body in that format — with confirmation, like the template button. Transformers of other ticket tools do not show up.

Opened tickets

The history icon opens the destination’s last 50 tickets, in a paginated grid, with search by ticket number. Each row carries date, number, origin (the alert, or “Opened manually by” whoever opened it) and the state:

The message icon opens the message summary, the same popup as in Messages, with the body sent and the tool’s response.

3. Link the destination to the alert

In the alert configuration, under Alerts, the Open a ticket in field lists the destinations, each with the tool’s icon, acronym and description — so it is clear in which system the ticket will open. An alert can open a ticket in more than one destination at the same time (a ticket for IT and a notification in SAP PM, for example).

For Application Offline, Only open a ticket after (minutes) also shows up, with 5 as the default: the e-mail goes out immediately, and the ticket only if the Application is still down after that time. A network blip of a few seconds does not become a ticket in the support queue. Zero opens it together with the alert.

The firing rules

• One ticket at a time. Once a ticket is open for a pair (alert configuration, destination), the same problem does not open another. The lock is released when the recovery alert arrives — Application Online or Interface Unblocked — and a new problem after that opens a new ticket.
• Condition Met is per occurrence. The condition alert already fires only once per crossing — and, split by key, once per piece of equipment. That is why it does not use the lock above: with it, furnace 2’s notification would wait for furnace 1’s to be normalized.
• Recovery does not open a ticket. The recovery alert only releases the lock; the team closes the ticket, in the tool.
• The tool does not call for help on itself. If the alert is about the tool itself (ServiceNow went down), opening a ticket in it would make no sense: the firing is recorded as Skipped, and the warning goes out by e-mail even if the configuration has no e-mail ticked.
• One destination does not hold up the others. If one destination fails, the others for the same alert open normally.

Open a ticket right away

Not every problem starts with an alert. Whoever sees something wrong can open the ticket directly.

From a failed message

On a message in Delivery Error, Business Error or Collection Error, the Open ticket button shows up next to PDF, Send by e-mail and Resend — in the message popup under Messages and on the detail page. It only shows up for users with the Open Ticket Tool on their profile, and when there is at least one active destination. A message that is itself a ticket does not offer the button.

That is where manual opening makes sense: anyone can fill in a blank form directly in the service tool; what CMS adds is the integration’s context. So the popup comes already filled in — and everything stays editable:

The destination fields follow the body per Application: changing the Application changes the fields. The operator only fills in what the destination left open — a value fixed in the body is not overwritten, and the popup does not create new keys. It is the way to open a PM notification with the equipment that only someone on the floor knows.

Only destinations with Available for manual opening on show up in the popup.

Open ticket shows a confirmation with the summary before sending. After sending, the popup follows the tool’s response and shows the ticket number as soon as it arrives — or the reason, if the tool rejects it. From there you can open another or, with access to ITSM Configuration, see the opened tickets.

Manual opening stays outside the one-ticket-at-a-time lock: whoever clicks wants a ticket now, and the automatic one can still open its own later.

Where the tool shows up in the rest of the system

The activated tool is an Application in the Help Desk category. It shows up where it helps follow the sending, and stays out of where it would only get in the way:

Permissions

There are three Tools, separated on purpose — whoever opens a ticket does not need to be able to create a destination, and whoever creates a destination does not need to be able to activate a tool:

The destination list in the Open ticket popup does not depend on the user having the tool’s Interface on their profile — an operator does not need it. What is protected there is the Application named in the ticket: only the Applications the user is allowed to see show up.

Common problems