AlertMagic - Configuring your Issue Management System

Introduction

Setting up your Issue Management System should be a quick task. Because every customer is different, we don't automate this part - but it is a simple exercise for most Issue Management Systems. You will typically need an account in the target system with permission to create and update the relevant records, plus its credentials.

Supported Issue Management Systems

The following Issue Management Systems (also called IT Service Management systems or ITSMs) are supported:

System	Notes
AutoTask PSA	Tickets are created and updated via the AutoTask API using an API user.
Cherwell	Incidents are managed via the Cherwell API.
ConnectWise Manage	Service tickets are managed via the ConnectWise Manage API.
Freshservice	Tickets are created and updated via the Freshservice API. See Freshservice below for the custom field it needs.
Jira	Issues are created and transitioned via the Jira REST API.
Microsoft Dynamics	Cases are managed via the Dynamics API.
ServiceNow	Incidents are managed via the ServiceNow REST API. You can enter the account as the full instance URL (for example https://dev123.service-now.com/) and AlertMagic converts it to the instance name automatically.
SolarWinds Service Desk	Incidents are managed via the Service Desk API; expression lookups commonly use its activeIncidents table.
No Action	A test system that accepts everything and writes nothing - useful for trying out configuration safely.

If you need to work with an alternative system, please contact support.

Freshservice

Freshservice cannot search tickets by their subject, so AlertMagic finds the open ticket for an alert through a ticket custom field that holds the problem signature. AlertMagic fills the field in when it creates a ticket, and a later alert with the same signature adds a note to that ticket rather than raising a new one. Only Open and Pending tickets count as open.

To set it up:

1. In Freshservice, create an agent for AlertMagic with a role that can create and update tickets, and copy that agent's API key.
2. In Freshservice, add a ticket custom field to hold the problem signature.
3. In Magic Suite, create a Freshservice Connection. Enter the full address of your Freshservice instance, for example https://yourcompany.freshservice.com/, paste the API key into the API Key field, and select AlertMagic Has Access. A sandbox has its own address, such as https://yourcompany-fs-sandboxname.freshservice.com/, and its own API key.
4. On the IMS page, choose the Connection. The Config JSON is filled in for you:

   {
   	"ProblemSignatureField" : "cf_problem_signature"
   }

   Change the value to your custom field's name as Freshservice uses it in ticket filters. AlertMagic will not start an Integration that uses this IMS until it is set.

Comments are added to tickets as private notes, so requesters are not emailed each time. To make them public, add "NotesArePrivate" : false to the Config JSON.

Mappings use the Freshservice field names, such as subject, description, email, group_id, workspace_id, status, priority and source. Custom fields are written as custom_fields/ followed by the field name. Status, priority and source accept a name, such as 'Urgent', as well as a number.

Freshservice lookups

Expressions can look Freshservice records up by name rather than hard-coding their ids. The criteria is always a key, an equals sign and a value:

Table	Criteria	Returns
activeIncidents	signature=	The open ticket carrying that problem signature
group	name=	An agent group
agent	email= or name=	An agent
requester	email= or name=	A requester
workspace	name=	A workspace
status, priority, urgency, impact, source	name=	The number for that name

For example, to set the group from its name:

am_lookup('ims', 'group', 'name=Network Operations', 'id', null, -1)

General configuration

Whatever the system, an IMS configuration comes down to the same ingredients:

• Account - which instance or company to talk to (an instance URL, account name, or company identifier, depending on the system).
• Username and secret - the credentials of the account AlertMagic uses. We recommend a dedicated service account so its activity is clearly identifiable in the target system.
• Incident number field - which field holds the human-facing incident number, so it can be reported in logs and metrics.

Tickets, Issues, Incidents, Comments and Problems

Because each Issue Management System has its own terminology, we abstract to the following:

Our term	Other terms
Issue	Abstractly, a ticket, issue, task, incident, problem.
Incident	A ticket, issue or task with the type "Incident"
Problem	A ticket, issue or task with the type "Problem"
Comment	A comment or note on an issue

Note: which tables, fields, and query strings a system supports (for example in expression functions such as am_lookup) is system-dependent - see Expression Functions (am_*) under Advanced for how expressions reach into the connected systems.