Rule Actions

A rule action is a configured delivery channel — the connection a Rule uses to notify someone or open a ticket when it raises an alert. Actions are defined once, here, and then assigned to as many rules as need them from each rule's Rule Actions tab.

Six action types exist: Email, Slack, SMS, Jira, Freshservice and Freshdesk.

Accessing Rule Actions

Navigate to Monitoring > Rules and open the Actions tab. Create new action at the top right opens the creation wizard. An existing action's settings are edited from its detail page: open the Configuration tab and click Manage action configuration. Export template, in the detail page's actions menu, opens the action as a Bicep template, with Open in Deploy, Download and Copy; see Deploy.

Creating an Action

The wizard runs in four steps:

1. General settings — the action's name, description and type.
2. Action configuration — the connection settings of the chosen type.
3. Action validation — a real test delivery to the configured destination.
4. Review and create — a summary of the settings before the action is created.

An action cannot be created until its test passes. The validation step sends a real message — for Jira, a real test issue; for Freshservice and Freshdesk, a real test ticket — and the wizard moves on only once that delivery succeeds. The same gate applies on the detail page: saving a changed configuration requires a fresh successful test.

Message Variables

A message can include details of the alert that triggered it. Type a variable, such as {{tenant_name}}, into a message field. When the notification is sent, the variable is replaced with its value. In the rule's action settings, the subject, summary, description and message template fields each have an Insert variable menu. Choose a variable there to add it where the cursor is. In a rule's custom field value, type the variable.

Variables work in these fields:

• Email: Subject Line and Message Template.
• Slack and SMS: Message Template.
• Jira: Summary, Description and the rule's custom field values.
• Freshservice and Freshdesk: Subject, Description and the rule's custom field values.

Variable	Value
{{severity}}	The severity of the alert: critical, high, medium or low.
{{message}}	What the rule found, for example CPU usage is 92% (threshold > 90%).
{{metric}}	What the rule measures, for example CPU usage or event volume.
{{current_value}}	The measured value, normally rounded to one decimal place, for example 92.4%. The notes below say when it keeps more. A data volume is written in a readable unit, for example 1.5 GB. Empty for a rule that does not compare a value with a threshold.
{{threshold}}	The threshold the value was compared with, for example > 90%. Empty for a rule that does not compare a value with a threshold.
{{timestamp}}	When the alert was raised, in UTC, for example 2026-10-28T09:15:00Z.
{{alert_id}}	The ID of the alert.
{{alert_url}}	A link that opens the alert in the console.
{{rule_name}}	The name of the rule that raised the alert.
{{rule_id}}	The ID of the rule.
{{rule_url}}	A link that opens the rule in the console.
{{resource_name}}	The name of the resource the alert is about.
{{resource_type}}	The type of resource the alert is about, such as a director or a device.
{{resource_id}}	The ID of the resource.
{{tenant_name}}	The name of the tenant the alert was raised in.
{{tenant_id}}	The ID of the tenant.
{{alert_count}}	How many alerts the notification covers. It is more than 1 when several alerts are grouped into one notification.
{{resource_list}}	The names of the resources the notification covers, separated by commas. A long list ends with "and N more".

Keep these points in mind:

• A placeholder that is not in the table is left as typed. For example, a misspelt {{resource}} appears in the message as the text {{resource}}.
• Spaces inside the braces are allowed. {{ rule_name }} works the same as {{rule_name}}.
• When several alerts are grouped into one notification, {{alert_id}} and {{alert_url}} refer to the first alert in the group.
• {{alert_url}} and {{rule_url}} open the console in the tenant you are working in. If you manage several tenants, switch to the alert's tenant before you open the link.
• If the tenant's name cannot be read when the notification is sent, {{tenant_name}} is left empty. The notification is still sent.
• {{current_value}} and {{threshold}} are filled in only for rules that compare one measured value with a threshold, such as CPU, memory, disk and queue usage. For other rules, such as status, baseline and event storm rules, they are empty. {{message}} describes what those rules found.
• {{current_value}}, and the value in {{message}}, keep more decimals, up to six, when rounding to one decimal place would put the value level with its threshold or on the other side of it: 95.04% against > 95%, not 95%. A data volume is written in the largest unit that keeps it at one or more.
• {{threshold}} keeps the unit the rule was written in, so a data volume can read 1.5 GB against a threshold of > 1000 MB. A director's queue usage rule in Size mode is the exception: its value and its threshold are both written in the largest unit that keeps them at one or more, for example queue usage is 612.4 MB (threshold > 500 MB). In Percentage mode both are percentages.
• The IDs are useful for matching a ticket to its alert, rule, resource or tenant, for example in a custom field.
• When several alerts are grouped into one notification and the text does not use {{alert_count}} or {{resource_list}}, the notification adds how many alerts and which resources it covers to the subject and the message.
• Custom field values set on the action itself cannot use variables. Set a value with variables on the rule instead.

Jira

A Jira action creates or updates issues in a Jira project. It connects to either Jira Cloud or Jira Data Center, and the deployment decides how it authenticates:

Deployment	Authentication
Jira Cloud	API token — an account email and API token, or OAuth 2.0 service account — a client ID and client secret
Jira Data Center	Personal Access Token only

Connection Settings

These fields are filled in on the Action configuration step, and are the same fields the detail page's Configuration tab edits.

Field	Shown for	Required	Description
Base URL	always	Y	The Jira site, over HTTPS only — for example, https://yourcompany.atlassian.net. It must be reachable at a public address — see the note below. A pasted REST URL such as …/rest/api/3/issue is trimmed to the site root when the field loses focus.
Deployment	always	Y	Jira Cloud or Jira Data Center.
Authentication Method	Jira Cloud	Y	API token (the default) or OAuth 2.0 service account. Data Center has no choice to make, so the field is not shown.
Account Email	Cloud, API token	Y	The Atlassian account the API token belongs to.
API Token	Cloud, API token	Y	Entered directly (Manual) or picked from the Vault (Vault).
Client ID	Cloud, OAuth	Y	The client ID of the service account's OAuth 2.0 credential.
Client Secret	Cloud, OAuth	Y	The credential's client secret. Manual or Vault.
Personal Access Token	Data Center	Y	Used instead of an API token. Manual or Vault.
Project Key	always	Y	The key of the space issues are created in — see the note below. Starts with an uppercase letter, followed by uppercase letters, digits or underscores — for example, OPS. Lowercase letters are uppercased as they are typed.
Issue Type	always	Y	The issue type's name as it appears in the space — for example, Task. It must exist in that space, or Jira refuses the issue.
Token expiry date (Optional)	API token and Data Center	N	A reminder date: the platform warns before the token expires. Not offered for OAuth, since a client secret is not a token a person issues.
Cloud ID (Optional)	Cloud, OAuth	N	The site's ID on Atlassian's API gateway. Leave it empty — see The Cloud ID.
Custom fields (Optional)	always	N	A part of the step of its own, after a divider: fields of the space's own, each with a Field name or ID, a Type and a fixed Value. They are sent on every issue the action opens, its test issue included. Up to 30 fields. A field the space made required must be listed here, or Jira refuses every issue the action opens, its test issue too, and the action cannot be created. See Custom Issue Fields.
Resolve alerts when the issue is closed	always	N	The last part of the step, after a divider, under Resolve alerts from Jira. Off by default. When it is on, VirtualMetric resolves an alert once the issue this action opened for it is closed. See Resolving Alerts from Jira.

note

Jira Cloud now calls projects spaces. Atlassian renamed them in Jira's own screens (Edit a space's details). The action, its REST API (projectKey) and Jira's REST API still say project. The Project Key is the space's key: the Key column under Spaces in Jira — for example, OPS.

note

An action that signs in with an API token or a Personal Access Token sends its issues and comments, with the credential, to the Base URL. The platform only sends them there when the Base URL resolves to a public address, on real deliveries and on the test alike:

Base URL resolves to	Result
A public address	Delivered
Loopback (127.0.0.0/8, ::1) or localhost	Refused
A private range (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, IPv6 unique local)	Refused
Link-local, including the cloud metadata address 169.254.169.254	Refused
Carrier-grade NAT (100.64.0.0/10)	Refused

The address is checked after the name is resolved, so a public hostname that resolves to one of the refused ranges is refused too. A refused delivery is not retried, and reports "the Jira base URL resolves to an address this service does not call".

Redirects are not followed. When the site answers with a redirect — for example, a reverse proxy sending requests on to another host — the delivery fails with "Jira rejected the issue (HTTP 3xx)". The Base URL must be the address that serves the Jira REST API directly.

A Jira Data Center instance reachable only on a private network cannot be used from the platform: it has to be published on a public HTTPS address. Actions using an OAuth 2.0 service account are not affected, since their requests go to Atlassian's own public hosts.

API Token or Service Account

With an API token, the action signs in as the person who issued the token, and issues it creates name that person as their reporter.

With an OAuth 2.0 service account, the action signs in as an Atlassian service account rather than a person. Issues it creates name the service account as their reporter. The client secret does not expire unless it is revoked, so there is no expiry date to track. Assigning an issue to a person still works as it does with an API token.

The platform exchanges the client ID and secret for a short-lived access token and fetches a new one as it needs to. A token Atlassian revokes before it expires is replaced on the next delivery, with nothing to do.

Setting Up the Service Account

Atlassian checks two separate things on every request the action makes, and both have to allow it. Set them up as separate steps: the scopes on the credential say nothing about which spaces the account may work in.

Layer	Decides	Where it is set
OAuth scopes	Which API operations the token may call at all	On the OAuth 2.0 credential, in Atlassian Administration
Jira access and space permissions	What the account may do in a given space	The service account's Jira access in Atlassian Administration, and the space's permissions in Jira

Do this in Atlassian before creating the action:

1. Create the service account and give it Jira access. In Atlassian Administration, go to Directory > Service accounts > Create a service account, and select a role for Jira on the site the action connects to. Jira access is separate from the space permissions in step 3: without it, the account cannot create issues at all. An organization gets five service accounts free, and more need Atlassian Guard; a service account with Jira access does not count toward the site's user limit. See Atlassian's Understand service accounts.

2. Create its OAuth 2.0 credential. On the service account, select Create credentials > OAuth 2.0, choose the scopes, then Create. Copy the client ID and client secret at the end: Atlassian does not show them again. See Atlassian's Create OAuth 2.0 credential for service accounts. Choose Jira scopes of one kind:

   • Classic scopes: read:jira-work, write:jira-work and read:jira-user.
   • Granular scopes, if you use those instead: all twelve that Atlassian's REST API reference lists for creating an issue and adding a comment — read:issue:jira, write:issue:jira, read:comment:jira, write:comment:jira, read:comment.property:jira, write:comment.property:jira, write:attachment:jira, read:project:jira, read:project-role:jira, read:user:jira, read:group:jira and read:avatar:jira.

3. Check the space permissions. In the space the action creates issues in, the account needs:

   • Browse projects
   • Create issues
   • Add comments
   • Assign issues

   Where they come from depends on the kind of space:

   • Company-managed space: its permission scheme (Grant or revoke permissions in a scheme). Look there first. A permission granted to Application access applies to every account with access to Jira, so the Jira access from step 1 covers it, and nothing needs adding in the space. A permission granted only to a space role needs the service account added to the space with a role that holds it. Do not use a guest role, which is for people outside the organization, the Service Desk roles, which belong to Jira Service Management, or atlassian-addons-project-access, which is reserved for apps.
   • Team-managed space: its access level (Team-managed space permissions). In an Open space everyone on the site creates, comments and assigns as a Member. In a Limited or Private space, add the service account with the Member role.

Then create the action: choose Jira Cloud, set Authentication Method to OAuth 2.0 service account, and enter the client ID and client secret. The client secret can be stored in the Vault and picked from there instead of being typed.

The Cloud ID

Requests made with a service account's token go through Atlassian's API gateway rather than to the site URL, and the gateway addresses a site by its Cloud ID. It is looked up from the Base URL when the action is tested or saved, and stored with the action, so the Cloud ID (Optional) field is normally left empty. Saving again with the same Base URL reuses the stored ID.

When the lookup fails, the test reports:

the site ID could not be looked up from the base URL; enter it manually

and saving marks the Cloud ID (Optional) field with "The cloud ID could not be looked up from the base URL. Enter it here." Enter the site's Cloud ID there and test again — Atlassian's How to find your Atlassian Cloud site's Cloud ID shows where to read it. A Cloud ID that is typed in is used as it is.

The lookup follows no redirects, and refuses a Base URL that resolves to a loopback, private or link-local address.

Delivery Errors

The test on the Action validation step reports the same message a failed delivery records. Only a busy or unreachable Jira is retried; every other failure stays failed, so alerts are not delivered until the action, the rule assignment or the space is fixed.

Cause	Reported as	Retried
Wrong client ID or client secret	"Atlassian rejected the OAuth client ID or secret (HTTP 401): …"	N
A scope missing from the credential, or a space permission missing for the account	Jira's own rejection — for example, "Jira rejected the issue (HTTP 403): …"	N
An issue type the space does not have	Jira's own rejection, naming the field	N
A priority the space does not have	Jira's own rejection, naming the field. When the site's priority list does not have the name either, the message adds "(the rule maps to "…", which is not one of the site's priorities: …)". See Priority Names	N
A required custom field left out, or a custom field whose Type does not match its type in Jira	Jira's own rejection, naming the field — for example, "Jira rejected the issue (HTTP 400): …". When Jira says the value must be a number, the message adds "(choose the Number type for this field; if it is the Organizations field, the account needs to read Jira's field list, read:field:jira on granular scopes)"	N
A custom field name that matches no custom field, or several	"Jira has no custom field named "…"; check the name, or enter the field's ID", or "2 Jira custom fields are named "…" (customfield_…, customfield_…); enter the ID of the one to fill"	N
The site's field list refused, while looking a custom field name up	"Jira refused the field list the custom field names are looked up in (HTTP 403): …"	N
A rule's Number value with a variable that does not render to a number	"the Jira custom field customfield_…: "critical" is not a number"	N
An organization's name instead of its ID in the Organizations field	"the Jira custom field customfield_…: "Acme" is not an organization ID; the Organizations field takes IDs, not names"	N
Jira or Atlassian answering HTTP 429 or 5xx, or not reachable	The status, or "could not reach Jira"	Y

Rule Assignment

When a Jira action is added on a rule's Rule Actions tab, its details step sets what the issues carry. This applies to every authentication method.

Field	Default	Description
Map severity levels to	Highest	The Jira priority every issue from this assignment gets, whatever the alert's severity. The list shows the priorities of the Jira site the action connects to, as Jira names them. When the site's list has been read and does not have the chosen priority, the field shows a warning, and the rule cannot be saved with it. When the site's priorities cannot be read, the field says so and lists the ones a new Jira Cloud site has: Highest, High, Medium, Low and Lowest. The site may have others, and no name is checked until its list can be read. A rule can set a different priority for each severity, as a template can. The field then lists them below it, and the rule keeps them until another priority is chosen here. See Priority Names.
Default Assignee (Optional)	—	On Jira Cloud, the user's Atlassian account ID — not their email address or name. It is the part after /jira/people/ in their Jira profile URL (Get an Atlassian Cloud user's account ID). On Jira Data Center, the username. The user must be one Jira lets issues in the space be assigned to. Left empty, no assignee is sent.
Labels (Optional)	—	Up to 20 labels added to every issue, none containing a space.
Custom fields	—	The rule's own values for the space's fields, in a list of its own below the issue settings. Each has a Field name or ID, a Type and a Value that may use the same variables as the summary. Up to 30 fields. For a field the action also sets, the rule's value wins. See Custom Issue Fields.
When the same alert fires again	Add comments to the existing issue	Comments on the issue the alert opened: at most once an hour while the alert stays open, at once when its severity rises, when it is resolved, and when it fires again after that. See Keeping the Issue up to Date. If the issue was resolved, closed or deleted, a new issue is created instead. Or Create a new issue: each time the alert fires again after it was resolved, a new issue is created, and no comments are added.
Summary	[{{severity}}] {{rule_name}} — {{resource_name}}	The issue summary. Line breaks are removed, and a summary longer than Jira's 255-character limit is cut to fit.
Description	The rule, the resource, the time it triggered and the alert's message, one per line	The issue description, one paragraph per line. A comment for an alert that fires again after it was resolved carries the same text. The other comments have their own text: the times seen and the latest reading, the severity change, or how the alert was resolved.

The summary, the description and the custom field values can use variables, such as {{tenant_name}} or {{current_value}}. See Message Variables for the full list.

The issue also carries the custom fields set on the action and on the rule assignment — see Custom Issue Fields. Nothing else is set on it — no components, due date or parent — and its reporter is always the account the action signs in as. Closing an alert does not close its issue. With Add comments to the existing issue, the issue gets a comment that says when and how the alert was resolved. With Resolve alerts when the issue is closed on, the opposite does happen: closing the issue resolves the alert. See Resolving Alerts from Jira.

note

The action's test issue carries none of the rule assignment. Every test — on the Action validation step, and after each configuration change — opens a real issue in the space, with the Summary and Description typed for the test. It is unassigned, unlabelled and on the space's default priority, which is expected rather than a failure. Of the custom fields, it carries only the action's own Custom fields (Optional). Its default description says it can be closed or deleted.

Keeping the Issue up to Date

With Add comments to the existing issue, the default, the alert's issue gets a comment at these moments:

• While the alert stays open, at most once an hour. The first comment comes an hour after the alert first fired. An acknowledged alert counts as open, so it gets these comments too. The limit is for each issue.
• At once, every time the alert's severity rises. The comment starts "Severity raised from High to Critical." These comments have no hourly limit.
• When the alert is resolved. The comment says when and how: by a person (with their resolution note), automatically after a set time, or because the condition was back to normal. The issue itself is not closed or resolved.
• When the alert fires again after it was resolved, as before.

Three rules sit around those moments:

• A closed issue gets a new one. When the same alert fires again after it was resolved, it creates a new issue if the earlier one is in Jira's Done status category, or was deleted. This holds whether or not Resolve alerts when the issue is closed is on.
• Comments go only to an issue that is still open. An issue in the Done status category, or deleted, gets no hourly, severity or resolved comment, and no issue is created for them. The rule's activity log shows, for example, "Rule action "X" did not send a notification: The Jira issue OPS-1 is done, so no comment was added."
• The issue that resolved its alert gets no resolved comment. When Resolve alerts when the issue is closed resolves an alert because its issue was closed, that issue gets no comment about it. Another action on the same rule still gets its own.

With Create a new issue, nothing here applies. Each time the alert fires again after it was resolved, a new issue is created, and no issue gets any of the comments above.

When several alerts are grouped into one notification, they share one issue. That issue gets at most one hourly comment for all of them. Severity and resolved comments come for each alert.

Email, Slack and SMS actions get none of these comments.

Resolving Alerts from Jira

With Resolve alerts when the issue is closed on, VirtualMetric resolves an alert once the issue the action opened for it is closed. The setting is off by default. It is the last part of the Action configuration step, after a divider, under Resolve alerts from Jira, and the detail page's Configuration tab edits it. The Review and create step and the detail page show it as Resolve Alerts on Close, Enabled or Disabled.

Question	Answer
What counts as closed	The issue's status is in Jira's Done status category, whatever the workflow calls the status.
How quickly	VirtualMetric checks every 5 minutes, so an alert is normally resolved within 5 minutes of its issue being closed. A check that fails on a rate limit or an outage is retried at the next one, so the alert can take longer.
Which alerts	Only alerts that are still open or acknowledged, and only through the newest issue the action opened or commented on for that alert. Closing an older issue does not resolve the alert while a newer one is still open.
Who resolved it	The alert's Resolved By and its timeline show Rule action: <action name>. The resolution note names the issue, for example Closed in Jira: OPS-123. The audit log gets an Alert resolved row under the same name.
Repeat alerts	When the same alert fires again, it does not comment on an issue someone has closed. It creates a new issue instead, so the closed one cannot resolve the new alert at once. This holds with the setting off too. See Keeping the Issue up to Date.
The other direction	Resolving an alert in VirtualMetric does not close its issue. With Add comments to the existing issue, the issue gets a comment that says when and how the alert was resolved, except when this setting resolved the alert because that issue was closed.
When the check fails	A refused credential or a missing permission is shown on the action's last delivery, as "Checking for closed tickets failed: …". A rate limit or an outage is retried on the next check.
The connection test	Turning the setting on or off on the create wizard keeps a test that has already passed.

Priority Names

Each Jira site has its own priorities. A Jira Cloud site starts with Highest, High, Medium, Low and Lowest. A Jira Data Center site often has Blocker, Critical, Major, Minor and Trivial instead, and an administrator can add more. So the platform checks a rule's priority names against the site the action connects to, not against a fixed list.

• A rule is saved only with priorities the site has. When a rule is saved, the platform reads the site's priorities with the action's own credentials. A name the site does not have is refused, and the error lists the site's priorities. This applies to a rule saved in the console, through the REST API, or from a deployment template.
• Capital letters do not matter. A name that differs from the site's only in case, such as high on a site that has High, is accepted and kept as written. Issues are sent with the site's spelling.
• The check never blocks a save when Jira cannot answer. When Jira cannot be reached within 5 seconds, or the account may not read the list, the rule is saved without the check. Its issues then carry the name as written, and Jira decides.
• The list is reused for 10 minutes. A priority added in Jira can be refused for up to 10 minutes after it is added.
• The check reads the site's list, not the space's. A space can use a priority scheme that leaves some of the site's priorities out. Jira still refuses an issue with such a priority.

A rule saved before these checks existed may hold a name in the wrong case. Its issues now go out with the site's spelling, without any change to the rule. A name the site does not have at all still fails, and the delivery error now lists the site's priorities. Change the rule's priority to fix it.

note

Reading the list is a separate request with its own scopes. An OAuth 2.0 service account on classic scopes needs nothing more: read:jira-work covers it. On granular scopes, Atlassian's Get priorities operation needs read:priority:jira, which the twelve scopes in Setting Up the Service Account do not include. Add it. Without it, priority names are not checked, and they go to Jira as written.

Custom Issue Fields

A Jira space can add fields of its own to its issues, and make one of them required: Jira then refuses every issue that leaves it out. Two lists set these fields, and both are sent:

List	Set on	Values	Sent on
Custom fields (Optional)	The action's Action configuration step, or its detail page's Configuration tab	Fixed	Every issue the action opens, its test issue included
Custom fields	A rule's assignment of the action	May use variables	The issues of that rule

A field the space requires goes on the action. An action cannot be created until its test issue is accepted, and the test issue carries the action's own fields only, so a required field set only on rules would leave the action failing its test. A rule can still set the same field to a value of its own.

Each field is added with Add field and has three parts:

• Field name or ID: the field's name as Jira shows it (for example, Organizations), its ID (customfield_10002), or the number alone (10002), which is saved as customfield_10002. A field can be listed once per list; names are compared without regard to case.
• Type: decides the JSON shape the value is sent in, and has to match the field's type in Jira — see the table below.
• Value: required, up to 4000 characters.

On the action's detail page, the Configuration tab shows the saved fields as a table, and the Review and create step of the wizard lists them.

Types

Type	For a Jira field of type	Value	Sent as
Text (text, URL, date)	Single-line text, URL, date picker, date time	The text as typed; a date as YYYY-MM-DD	A string
Paragraph	Multi-line text	The text	A document on Jira Cloud, as the description is; a string on Jira Data Center
Number	Number	A number such as 3 or 2.5	A JSON number, exactly as written
Select list	Select list, radio buttons	The option's name as Jira shows it	{"value": "…"}
Multi select / checkboxes	Multi select, checkboxes	Option names, separated by commas	A list of {"value": "…"}
Labels	Labels	Entries separated by commas or spaces	A list of strings
User (account ID on Cloud, username on Data Center)	User picker	The user's account ID on Jira Cloud, their username on Jira Data Center	{"accountId": "…"} on Cloud, {"name": "…"} on Data Center

Organizations, the Jira Service Management field that names an issue's customer organizations, takes organization IDs as numbers — [12, 34] — which none of these types sends. The field is recognised by its type in the site's field list, and its values are then sent as numbers whichever Type is chosen. Choose Labels, which takes several IDs separated by commas or spaces. A value that is not an ID, such as an organization's name, fails the delivery naming the field. See the example in Action and Rule Together.

Fixed Values and Variables

• On the action, a value is fixed. A value that uses one of the summary's variables, such as {{resource_name}}, is refused with "Enter a fixed value. A value with variables can be set on the rule.", because the test issue has no alert to fill it from.
• On a rule, a value may use the same variables as the summary. A Number value without a variable is checked when the assignment is saved. One with a variable can only be checked once the alert renders it: if it is not a number then — {{severity}} renders to critical — the delivery fails naming the field.
• A value that renders to nothing is left out of the issue, so Jira applies the field's default or, when the field is required, refuses the issue naming it.

Field Names

A field given by its name is looked up in the site's list of custom fields when an issue is opened, without regard to case, and the list is reused for 10 minutes, so a field added or renamed in Jira is picked up within that time. Only custom fields can be set — a system field such as Components or Due date is not in that list.

The list is read for fields given by their IDs as well, to recognise the Organizations field. A field given by its ID never fails over it: when the list cannot be read, the field is sent in the shape its Type sends. A refusal is remembered for 10 minutes for that account, so a scope or permission granted afterwards reaches fields given by ID within that time; a field given by its name asks again on every issue.

A name that matches no custom field, or more than one, fails the delivery naming it; enter the field's ID instead. On a site that names two fields alike, the error lists their IDs.

note

The lookup is a separate request with its own scopes. An OAuth 2.0 service account on classic scopes needs nothing more: read:jira-work covers it. On granular scopes, Atlassian's Get fields operation also needs read:field:jira, read:project-category:jira and read:field-configuration:jira, which the twelve scopes in Setting Up the Service Account do not include. Add them. Fields named by their IDs are still sent without them, but the Organizations field is then not recognised: its IDs go out as text, which Jira refuses with "Operation value must be a number".

Action and Rule Together

The two lists are resolved to IDs first, so Organizations on the action and customfield_10002 on a rule are the same field. When both set a field, the rule's value is sent, unless it renders to nothing, in which case the action's is. The action's other fields are sent as they are.

Custom fields are set when an issue is opened. A comment on an existing issue changes no fields; an issue opened because the earlier one was resolved, closed or deleted carries them.

For example, a Jira Service Management space that requires Organizations (customfield_10002), a field that takes organization IDs, not names. Atlassian's Update the Organizations field shows how to find an organization's ID.

1. On the action, add Organizations with type Labels and the default organization's ID as its value, for example 12. It is sent as [12] on every issue, the test issue included, so the action can be created.
2. On a rule for another organization, add the same field with that organization's ID. That rule's issues carry its ID instead.

Editing a Jira Action

• Existing actions keep working unchanged. An action created before the service-account option existed opens with Authentication Method set to API token.
• Switching the authentication method asks for the new method's secret — the API token or the client secret — because nothing is stored for it yet.
• Changing the Base URL asks for the secret again, whichever method the action uses.

REST API

In a rule action's configuration, the Jira settings live under properties.jira. The keys the authentication choice adds, the action's own custom fields, and resolving alerts from closed issues:

Key	Description
authMethod	api_token or oauth_client_credentials for Jira Cloud. Omitted or empty means api_token, which is how actions created before this key existed are stored. Omitted on Data Center.
clientId	The service account credential's client ID.
clientSecret	The client secret, as {"source": "manual", "value": "…"} or {"source": "vault", "secretId": <id>}.
cloudId	The site's Cloud ID. Optional: left empty, it is looked up from baseUrl and stored.
customFields	Ordered list of {name, type, value}, sent on every issue the action opens, the test issue included. type is text (the default), paragraph, number, option (Select list), options (Multi select / checkboxes), labels or user. name is the field's name, at most 255 characters, or its ID: customfield_10002, or 10002, which is stored as customfield_10002. Names are unique without regard to case. value is required, at most 4000 characters, and may not use variables. At most 30. A response carries an empty list when there are none.
resolveAlertOnClose	true resolves an alert once the issue the action opened for it is in Jira's Done category. Omitted or false means off. See Resolving Alerts from Jira.

A configuration carries the fields of one authentication method only. One that mixes two methods' fields is refused — for example, clientId alongside apiToken.

In a rule's assignment of the action, the issue settings live under ruleSettings.jira:

Key	Description
summaryTemplate	The issue summary. Required, at most 255 characters.
descriptionTemplate	The issue description, at most 4000 characters. Omitted or empty, the issue has no description.
priorityMapping	Severity (critical, high, medium, low) to a Jira priority name. A severity left out gets the space's default priority. The console maps every severity of the assignment to the one name chosen. Each name must be a priority the Jira site has, or the request is refused with status 400. Capital letters do not matter, and the name is stored as written. See Priority Names.
assignee	The account ID on Jira Cloud, the username on Data Center.
labels	Up to 20 labels, none empty or containing whitespace.
repeatBehaviour	new_issue or comment_on_existing. Omitted means comment_on_existing.
customFields	The rule's own custom fields, in the shape properties.jira.customFields takes, except that a value may use the template variables. For a field both set, this value wins unless it renders empty. Omitted means none.

Freshservice and Freshdesk

A Freshservice or Freshdesk action opens a ticket in a Freshworks helpdesk when an alert fires, and can keep that ticket up to date with private notes while the alert is open, when its severity rises, when it is resolved and when it fires again. The two products are separate action types but share every field except the workspace, which only Freshservice has.

Connection Settings

These fields are filled in on the Action configuration step, and are the same fields the detail page's Configuration tab edits.

Field	Shown for	Required	Description
Domain	both	Y	The account's host on the vendor's own domain — for example, acme.freshservice.com or acme.freshdesk.com. The account name alone is enough: acme is completed with the vendor domain when the field loses focus, and a pasted portal URL is trimmed to its host. A custom portal domain is not accepted, because every account also has the vendor one and the API key is only ever sent there. Typing the other product's domain shows "This is a Freshdesk domain. Go back to General settings and choose Freshdesk as the action type."
API Key	both	Y	Entered directly (Manual) or picked from the Vault (Vault). Tickets are opened as the account the key belongs to — see The API Key.
Requester Email	both	Y	Who the ticket is raised on behalf of. Both products require a requester.
Workspace ID (Optional)	Freshservice	N	Places tickets in one workspace of an account that has several. Left empty, tickets go to the primary workspace. Digits only.
Custom fields	both	N	A part of the step of its own, after a divider: the account's own ticket fields, sent on every ticket the action opens, its test ticket included. Each has an API name, a Type (Text, Number or Checkbox) and a fixed Value. Up to 30 fields. A field the account made required must be listed here, or Freshservice or Freshdesk refuses every ticket the action opens, its test ticket too, and the action cannot be created. See Custom Fields.
Resolve alerts when the ticket is resolved or closed	both	N	The last part of the step, after a divider, under Resolve alerts from Freshservice or Resolve alerts from Freshdesk. Off by default. When it is on, VirtualMetric resolves an alert once the ticket this action opened for it is resolved or closed. See Resolving Alerts from Freshservice or Freshdesk.

On the action's detail page, the Configuration tab shows the saved custom fields as a table, and the Review and create step of the wizard lists them.

The API Key

• Freshdesk: use the agent's own key, under Profile Settings > View API Key.
• Freshservice: new accounts disable personal API keys, and the profile page then reads "Your API key is disabled. Please contact your admin to enable it." Use an Integration User instead — a non-login account for integrations:
  1. In Freshservice, go to Admin > User Management > Integration Users and click Create integration user.
  2. Give it a role that can create and update tickets. On an account with several workspaces, a role applies only in the workspace it is added to: on the user's Permissions tab, click Add to workspace, pick the workspace the action's Workspace ID (Optional) names (the primary workspace when the field is empty), and add the role there.
  3. Copy the key from its API key card.
• Freshservice for MSPs: Integration Users are not available, because Freshworks leaves MSP accounts out of the feature. Use the personal key of an agent with a role that can create and update tickets, under Profile Settings. An agent's API key stays off until an admin turns it on. Prefer a full-time agent: Freshworks charges a day pass when an occasional agent's key is used by an integration.

Rule Assignment

When a Freshservice or Freshdesk action is added on a rule's Rule Actions tab, its details step sets what the tickets carry:

Field	Default	Description
Priority	By severity	By severity files critical alerts as Urgent, high as High, medium as Medium and low as Low. A fixed choice — Urgent, High, Medium or Low — applies one priority to every severity. On a Freshservice account whose Priority Matrix is on, the matrix decides the priority — see Freshservice's Priority Matrix.
Tags (Optional)	—	Up to 20 tags added to every ticket.
Group ID (Optional) / Agent ID (Optional)	—	The numeric IDs at the end of the group's or agent's page URL in Freshworks. Left empty, the account's own assignment rules apply.
When the same alert fires again	Add private notes to the existing ticket	Adds private notes to the ticket the alert opened: at most once an hour while the alert stays open, at once when its severity rises, when it is resolved, and when it fires again after that. See Keeping the Ticket up to Date. If the ticket was resolved, closed or deleted, a new ticket opens instead. Or Open a new ticket: each time the alert fires again after it was resolved, a new ticket opens, and no notes are added.
Custom fields	—	The account's own ticket fields, added one at a time. Each has an API name (Freshservice lists the fields under Admin > Field Manager, Freshdesk under Admin > Ticket Fields; on Freshdesk it starts with cf_), a Type (Text, Number or Checkbox) and a Value that may use the same variables as the subject. Up to 30 fields. A field the account made required belongs on the action, so the action's test ticket passes; set it here only to give this rule's tickets a value of their own. For a field the action also sets, the rule's value wins. See Custom Fields.
Subject / Description	the same defaults as Jira	Supports variables, such as {{tenant_name}} or {{alert_url}}. See Message Variables.

Freshservice's Priority Matrix

Freshservice has a Priority Matrix, under Admin > Service Desk Settings > Priority Matrix. When an account turns it on, Freshservice ignores the priority a ticket is sent with and works the priority out from the ticket's urgency and impact instead. On an account with several workspaces, each workspace has its own matrix: the one that counts is in the workspace the action's Workspace ID (Optional) names (the primary workspace when the field is empty). So a Freshservice ticket carries an urgency and an impact as well as the chosen priority:

Chosen priority	Urgency	Impact
Low	Low	Low
Medium	Medium	Medium
High	High	Medium
Urgent	High	High

• With the Priority Matrix off, the ticket gets the chosen priority.
• With the Priority Matrix on and its cells as Freshservice ships them, the pairs above give the chosen priority back, so the ticket still gets it.
• With a matrix whose cells an admin has changed, the account's own matrix decides the priority from the urgency and impact above. VirtualMetric cannot read the matrix, so it cannot adjust the pairs to it.
• The action's test ticket is sent as Low, with urgency Low and impact Low. With the Priority Matrix on, the matrix's Low/Low cell decides the priority it is filed with, so a changed cell can file it differently.

Freshdesk has no urgency or impact fields and no Priority Matrix, so a Freshdesk ticket always gets the chosen priority.

Custom Fields

A Freshservice or Freshdesk account can add fields of its own to its ticket form, and make one of them required: the product then refuses every ticket created through its API that leaves it out. Two lists set these fields, and both are sent:

List	Set on	Values	Sent on
Custom fields	The action's Action configuration step, or its detail page's Configuration tab	Fixed	Every ticket the action opens, its test ticket included
Custom fields	A rule's assignment of the action	May use variables	The tickets of that rule

A field the account requires goes on the action. An action cannot be created until its test ticket is accepted, and the test ticket carries the action's own fields only, so a required field set only on rules would leave the action failing its test. A rule can still set the same field to a value of its own.

Each field is added with Add field. A custom field's Type decides how its value is sent:

• Text covers text, paragraph, dropdown and date fields. The value is sent as a string.
• Number is sent as a JSON number, exactly as written.
• Checkbox is sent as true or false.

Fixed Values and Variables

• On the action, a value is fixed. A value that uses one of the subject's variables, such as {{resource_name}}, is refused with "Enter a fixed value. A value with variables can be set on the rule.", because the test ticket has no alert to fill it from.
• On a rule, a value may use the same variables as the subject.
• A literal Number or Checkbox value is checked when the action or the assignment is saved.
• A value with a variable can only be checked when the alert is sent. If it does not fit its type then — for example, {{severity}} in a Number field renders to critical — that delivery fails with a message naming the field.

Action and Rule Together

Fields are matched by their API name, so the same name on the action and on a rule is the same field. When both set a field, the rule's value is sent, unless it renders to nothing, in which case the action's is. The action's other fields are sent as they are.

Custom fields are set when a ticket is opened. A note added to an existing ticket changes no fields. A ticket opened because the earlier one was resolved, closed or deleted carries them.

Tickets and Notes

• A new ticket opens with status Open.
• The description is sent as HTML, with the alert text escaped.
• Every note is private.
• Resolving an alert does not close its ticket. With Add private notes to the existing ticket, the ticket gets a note that says when and how the alert was resolved. With Open a new ticket, nothing is sent.
• Closing the ticket can resolve the alert. With Resolve alerts when the ticket is resolved or closed on, a ticket set to Resolved or Closed resolves the alert it was opened for. See Resolving Alerts from Freshservice or Freshdesk.
• A resolved or closed ticket gets no more notes, whether or not that setting is on. When the same alert fires again, it opens a new ticket instead. See Keeping the Ticket up to Date.

Keeping the Ticket up to Date

With Add private notes to the existing ticket, the default, the alert's ticket gets a private note at these moments:

• While the alert stays open, at most once an hour. The first note comes an hour after the alert first fired. An acknowledged alert counts as open, so it gets these notes too. The limit is for each ticket.
• At once, every time the alert's severity rises. The note starts "Severity raised from High to Critical." These notes have no hourly limit.
• When the alert is resolved. The note says when and how: by a person (with their resolution note), automatically after a set time, or because the condition was back to normal. The ticket itself is not closed or resolved.
• When the alert fires again after it was resolved, as before.

Three rules sit around those moments:

• A closed ticket gets a new one. When the same alert fires again after it was resolved, it opens a new ticket if the earlier one is resolved or closed in Freshservice or Freshdesk, or was deleted. This holds whether or not Resolve alerts when the ticket is resolved or closed is on.
• Notes go only to a ticket that is still open. A resolved, closed or deleted ticket gets no hourly, severity or resolved note, and no ticket is opened for them. The rule's activity log shows, for example, "Rule action "X" did not send a notification: The Freshservice ticket 4711 is resolved or closed, so no note was added."
• The ticket that resolved its alert gets no resolved note. When Resolve alerts when the ticket is resolved or closed resolves an alert because its ticket was closed, that ticket gets no note about it. Another action on the same rule still gets its own.

With Open a new ticket, nothing here applies. Each time the alert fires again after it was resolved, a new ticket opens, and no ticket gets any of the notes above.

When several alerts are grouped into one notification, they share one ticket. That ticket gets at most one hourly note for all of them. Severity and resolved notes come for each alert.

Email, Slack and SMS actions get none of these notes.

Resolving Alerts from Freshservice or Freshdesk

With Resolve alerts when the ticket is resolved or closed on, VirtualMetric resolves an alert once the ticket the action opened for it is resolved or closed. The setting is off by default. It is the last part of the Action configuration step, after a divider, under Resolve alerts from Freshservice or Resolve alerts from Freshdesk, and the detail page's Configuration tab edits it. The Review and create step and the detail page show it as Resolve Alerts on Resolve or Close, Enabled or Disabled.

Question	Answer
What counts as closed	The ticket's status is Resolved or Closed, the built-in statuses 4 and 5. A custom status does not count, and neither does a deleted ticket.
How quickly	VirtualMetric checks every 5 minutes, so an alert is normally resolved within 5 minutes of its ticket being resolved or closed. A check that fails on a rate limit or an outage is retried at the next one, so the alert can take longer.
Which alerts	Only alerts that are still open or acknowledged, and only through the newest ticket the action opened or added a note to for that alert. Closing an older ticket does not resolve the alert while a newer one is still open.
Who resolved it	The alert's Resolved By and its timeline show Rule action: <action name>. The resolution note names the ticket, for example Closed in Freshservice: ticket 4711 or Closed in Freshdesk: ticket 4711. The audit log gets an Alert resolved row under the same name.
Repeat alerts	When the same alert fires again, it does not add a note to a ticket someone has resolved or closed. It opens a new ticket instead, so the closed one cannot resolve the new alert at once. This holds with the setting off too. See Keeping the Ticket up to Date.
The other direction	Resolving an alert in VirtualMetric does not close its ticket. With Add private notes to the existing ticket, the ticket gets a note that says when and how the alert was resolved, except when this setting resolved the alert because that ticket was closed.
When the check fails	A refused API key or a missing permission is shown on the action's last delivery, as "Checking for closed tickets failed: …". A rate limit or an outage is retried on the next check.
The connection test	Turning the setting on or off on the create wizard keeps a test that has already passed.

Editing a Freshservice or Freshdesk Action

Changing the Domain asks for the API key again, the same rule as a Jira action's Base URL.

REST API

In a rule action's configuration, the settings live under properties.freshservice or properties.freshdesk:

Key	Description
domain	The account host, for example acme.freshservice.com.
apiKey	The API key, as {"source": "manual", "value": "…"} or {"source": "vault", "secretId": <id>}.
requesterEmail	Who tickets are raised on behalf of.
workspaceId	Freshservice only, a string of digits. Refused on Freshdesk.
customFields	Ordered list of {name, type, value}, sent on every ticket the action opens, the test ticket included. type is text (the default), number or checkbox. name is the field's API name: letters, digits and underscores, at most 128 characters, unique. value is at most 1000 characters and may not use variables. At most 30. A response carries an empty list when there are none.
resolveAlertOnClose	true resolves an alert once the ticket the action opened for it is Resolved or Closed. Omitted or false means off. See Resolving Alerts from Freshservice or Freshdesk.

In a rule's assignment of the action, the ticket settings live under ruleSettings.freshservice or ruleSettings.freshdesk:

Key	Description
subjectTemplate	The ticket subject. Required.
descriptionTemplate	The ticket description.
priorityMapping	Severity (critical, high, medium, low) to priority, 1 (Low) to 4 (Urgent). A severity left out takes its By severity default.
groupId	Optional group ID, a string of digits.
agentId	Optional agent ID, a string of digits.
tags	Up to 20 tags.
repeatBehaviour	new_ticket or note_on_existing. Omitted means note_on_existing.
customFields	Ordered list of {name, type, value}. type is text (the default), number or checkbox. name is the field's API name: letters, digits and underscores, unique. At most 30. For a field the action also sets, this value wins unless it renders empty. Omitted means none.