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.

Seven action types exist: Email, Slack, Microsoft Teams, 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. For Microsoft Teams, a passed test means that Teams received the message, so check the channel for the card. See The Test Card.

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, Microsoft Teams 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% on dir-02 (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.
{{window}}	The rule's time period in words, in the largest unit that divides it exactly: 5 minutes for 300 seconds, 1 hour for 3600, 90 seconds for 90, 90 minutes for 5400, 1 day for 86400. Filled in for every rule that has a time period, status rules included, and empty only for a rule that has none. For example, {{metric}} was {{current_value}} over {{window}} ({{threshold}}) reads CPU usage was 97.2% over 5 minutes (> 95%).
{{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.
• For a Director's CPU, memory and disk usage rules, and its queue usage rule in Percentage mode, {{message}} also says which machine, disk or queue the value came from: CPU usage is 97.2% on dir-02 (threshold > 95%), disk usage is 91% on dir-02, /data (threshold > 90%), queue usage is 85% on dir-01, persistent sending queue (threshold > 80%). {{current_value}} stays the bare value, such as 97.2%. Every other rule's message reads as before.
• {{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.

Microsoft Teams

A Microsoft Teams action posts a card to a Teams channel for each notification its rules send. A notification is normally about one alert. When several alerts are grouped into one notification, one card covers them all. The card's title names the severity, the rule and the resource, for example [critical] CPU usage on dir-west-1. Below the title is the text of the rule's Message Template.

The action posts through a Teams workflow. A workflow is an automation that you create in the Workflows app of Teams, which runs on Power Automate. When you create a webhook workflow for a channel, Teams gives you a URL. VirtualMetric sends each notification to that URL, and the workflow posts it to its channel. An Azure Logic App that receives a webhook request and posts to Teams works the same way.

Before you start, check that you have these:

• A Microsoft 365 work or school account. The free version of Teams has no Workflows app.
• The Workflows app. If Teams does not show Workflows, or says the app is blocked, a Teams administrator has to allow the Workflows app for your organization.
• An app in Microsoft Entra ID, only for the two tenant settings. See Who Can Trigger the Workflow. If your organization does not let users register apps, an administrator has to register it for you.

The steps below quote Microsoft's labels in English. The labels can differ slightly in your Teams language, and Microsoft changes them from time to time.

Who Can Trigger the Workflow

The workflow's trigger has a setting named Who can trigger the flow?. It decides who may send messages to the workflow's URL. The action's Who can trigger the workflow field must match it.

Setting	What the action needs	What it means
Anyone	The webhook URL	Anyone who has the URL can post to the channel. The URL works like a password, so keep it private.
Any user in my tenant	The webhook URL and an app in Microsoft Entra ID	VirtualMetric signs in as the app and sends the app's token with every card it posts. The URL alone is not enough to post.
Specific users in my tenant	The webhook URL and an app in Microsoft Entra ID, with the app added to the trigger's allowed users	Only the users and apps that the trigger lists can post.

Anyone needs the fewest steps. Choose a tenant setting when your organization does not allow workflows that anyone can trigger, or when the URL alone should not be enough to post.

Step 1: Create the Workflow in Teams

1. In Teams, go to the channel that should receive the alerts. We recommend a standard channel, because Teams handles workflow posts to private channels differently.
2. Next to the channel's name, select More options (…), and then select Workflows. You can also open Apps > Workflows and select Create.
3. Search for webhook, and select the Send webhook alerts to a channel template.
4. Enter a name for the workflow, for example VirtualMetric alerts.
5. Choose the Team and the Channel that the workflow posts to, and select Add workflow.
6. Copy the URL that Teams shows when the workflow is created. You enter it in the action's Webhook URL.

The URL starts with https:// and is on api.powerplatform.com. The action also accepts a URL on logic.azure.com, which is where an Azure Logic App's URL is. A Teams workflow's old URL on logic.azure.com stopped working on 30 November 2025, so always copy the current URL from the workflow's trigger (Changes to HTTP or Teams Webhook trigger flows).

Step 2: Set Who Can Trigger the Workflow

The Send webhook alerts to a channel template starts with Anyone. If you keep Anyone, skip this step.

1. Open the workflow to edit it. In Teams, open the Workflows app and select the workflow. You can also open it in Power Automate, under My flows.
2. Select the trigger, When a Teams webhook request is received.
3. Set Who can trigger the flow? to Any user in my tenant or Specific users in my tenant.
4. For Specific users in my tenant, leave the allowed users as they are for now. You add the app to them in step 4, after you register it.
5. Save the workflow.
6. Copy the URL from the trigger's HTTP URL field.

warning

The URL changes when you change who can trigger the flow. A URL that you copied before the change stops working. Copy the URL again from the trigger, and enter it in the action.

An empty list of allowed users is an exception to the table above. With Specific users in my tenant and no allowed users, Power Automate lets any user in the tenant trigger the workflow. So add the app in step 4, and check that the list holds only the users and apps that should post (Add OAuth authentication for HTTP request triggers).

Step 3: Register an App in Microsoft Entra ID

Do this step only for Any user in my tenant or Specific users in my tenant. VirtualMetric signs in as this app when it posts a card. Register the app in the same tenant as the workflow.

1. Sign in to the Microsoft Entra admin center.
2. Go to Entra ID > App registrations, and select New registration. In some versions of the admin center, the path is Identity > Applications > App registrations.
3. Enter a name for the app, for example VirtualMetric Teams alerts.
4. Under Supported account types, choose the single-tenant option: Single tenant only, or Accounts in this organizational directory only in older versions.
5. Leave Redirect URI empty, and select Register.
6. On the app's Overview page, copy two values:
   • Directory (tenant) ID goes in the action's Tenant ID.
   • Application (client) ID goes in the action's Client ID.
7. Go to Certificates & secrets > Client secrets, and select New client secret. Enter a description, choose when the secret expires, and select Add.
8. Copy the secret's Value at once, and enter it in the action's Client secret. Do not copy the Secret ID. Microsoft shows the value only until you leave the page.

The app does not need any API permissions. Leave the API permissions page as it is.

warning

A client secret expires. Microsoft allows a lifetime of at most 24 months and recommends less than 12 (Add and manage app credentials). When the secret expires, Microsoft Entra ID refuses the sign-in and no alerts reach the channel. Before the expiry date, create a new secret, enter it in the action's Client secret, and send the test again. Then delete the old secret.

Step 4: Allow the App to Trigger the Workflow

Do this step only for Specific users in my tenant.

1. In the Microsoft Entra admin center, go to Entra ID > Enterprise apps (in older versions, Enterprise applications), and open the app you registered.
2. On its Overview page, copy the Object ID.
3. In the workflow's trigger, add this object ID to the allowed users, and save the workflow.

note

Use the object ID from Enterprise apps. The app has a different ID on each page. Its Application (client) ID and the Object ID on its App registrations page are not accepted by the trigger. If the wrong ID is listed, or none, the action's test fails, and its error names the object ID to add.

Step 5: Create the Action in VirtualMetric

1. Go to Monitoring > Rules, open the Actions tab, and select Create new action.
2. On the General settings step, enter a name, and choose Microsoft Teams as the type.
3. On the Action configuration step, fill in the fields. See Teams Connection Settings.
4. On the Action validation step, select Send test notification, and check that the card appears in the channel. See The Test Card.
5. On the Review and create step, check the settings, and create the action.
6. Add the action to a rule: on the rule's Rule Actions tab, select Manage rule actions and Add new action. Choose Microsoft Teams, then the action, and set its severities and its Message Template. See Teams Rule Assignment.

Teams Connection Settings

These fields are on the Action configuration step. The detail page's Configuration tab edits the same fields.

Field	Shown for	Required	Description
Webhook URL	always	Y	The workflow's URL, from step 1, or from step 2 if you changed who can trigger the flow. It must start with https:// and be on api.powerplatform.com or logic.azure.com. Enter it directly (Manual) or pick it from the Vault (Vault). The action keeps it as a secret, because with Anyone the URL alone lets anyone post to the channel.
Who can trigger the workflow	always	Y	Anyone (the default), Any user in my tenant or Specific users in my tenant. Choose the same setting as Who can trigger the flow? in the workflow's trigger.
Tenant ID	the two tenant settings	Y	The Directory (tenant) ID from the app's Overview page, for example aaaabbbb-0000-cccc-1111-dddd2222eeee. A domain name of the tenant, such as contoso.onmicrosoft.com, also works.
Client ID	the two tenant settings	Y	The Application (client) ID from the app's Overview page.
Client secret	the two tenant settings	Y	The Value of the app's client secret, not its Secret ID. Manual or Vault.
Channel name (Optional)	always	N	A name for the channel, up to 100 characters. It is shown in the console only. Teams always posts to the channel that the workflow belongs to.

With Any user in my tenant or Specific users in my tenant, the step shows a notice about the app in Microsoft Entra ID. With Specific users in my tenant, a second notice says to add the app's object ID to the trigger's allowed users. When you switch an action back to Anyone and save it, the action no longer keeps the app's details.

The action signs in through Microsoft's global cloud. Workflows in Microsoft's government clouds or in the cloud operated in China, whose URLs are on other domains, cannot be used.

The Test Card

The Action validation step sends a test message to the workflow, which posts it to the channel as a card. The card's text is the step's Message Template, which starts with a test message that you can change. The rule's own message is set later, when you add the action to a rule.

A successful test means that Teams received the message, not that it posted it. The workflow accepts the message first and posts the card afterwards, and Teams does not report whether posting worked. So check the channel after the test. If no card appears, open the workflow's run history in Teams or Power Automate to see why it did not post.

Teams Rule Assignment

When a Microsoft Teams action is added on a rule's Rule Actions tab, its details step sets the severities that trigger it and the message it posts:

Field	Default	Description
Message Template	**{{severity}}** · {{rule_name}}, then {{resource_type}} {{resource_name}} — {{message}}, then _{{timestamp}}_, one per line	The text below the card's title, up to 3000 characters. Select Insert variable to add a variable, such as {{current_value}} or {{alert_url}}. See Message Variables.

How the card shows the message:

• The title is fixed. It is always [{{severity}}] {{rule_name}} on {{resource_name}}, and the message template does not change it.
• Each line of the template is a line on the card. An empty line adds space before the next line.
• The card understands simple formatting: **bold**, _italic_, lists and links written as [text](https://…).
• A very long message is cut and ends with …, so the card stays within the size that Teams accepts.

Teams Delivery Errors

The test on the Action validation step reports the same message that a failed delivery records. Only a busy or unreachable service is retried. Every other failure stays failed, and alerts do not reach the channel until the action or the workflow is fixed.

Cause	Reported as	What to do	Retried
The action is set to Anyone, but the trigger accepts only signed-in users	"Microsoft Teams rejected the message (HTTP 401): DirectApiAuthorizationRequired: …. In the workflow's trigger, set "Who can trigger the flow" to "Anyone" and use the new URL that the trigger shows, or choose the trigger's setting in this action and enter a Microsoft Entra ID app"	Set the trigger to Anyone and copy its new URL into the action. Or keep the trigger's setting, choose it in the action, and enter the app's details.	N
Microsoft Entra ID refuses the app: a wrong or expired client secret, an unknown tenant, or an unknown client ID	"Microsoft Entra ID refused the app's credentials: AADSTS…", with Microsoft's code and reason, for example "AADSTS7000215: Invalid client secret provided."	Check the value that the code names. For a client secret, enter its Value, not its Secret ID, or create a new secret.	N
Any user in my tenant: the trigger refuses the app's token	"Microsoft Teams rejected the message (HTTP 401): …. Check that "Who can trigger the flow" in the workflow's trigger matches this action, and that the app is registered in the same tenant as the workflow" (or HTTP 403)	Check the trigger's setting, and that the app and the workflow are in the same tenant.	N
Specific users in my tenant: the app is not on the trigger's allowed users	"Microsoft Teams rejected the message (HTTP 401): …. In the workflow's trigger, add the app's object ID, aaaabbbb-0000-cccc-1111-dddd2222eeee, to the users who can trigger the flow" (or HTTP 403)	Add the object ID that the message names to the trigger's allowed users, and save the workflow.	N
The workflow refuses the message for another reason, for example because it was deleted or turned off	"Microsoft Teams rejected the message (HTTP …): …", with the reason the workflow gave	Check the workflow in Teams. If it was created again, copy its new URL into the action.	N
The URL answers with a redirect	"Microsoft Teams answered with a redirect (HTTP 3xx), which is not followed"	Copy the URL again from the workflow's trigger.	N
Teams or Microsoft Entra ID answers HTTP 429 or 5xx, or cannot be reached	The status, or "could not reach Microsoft Teams" or "could not reach Microsoft Entra ID"	Nothing. The delivery is tried again.	Y

The errors never show the webhook URL, the client secret or the app's token.

Editing a Microsoft Teams Action

• When you change who can trigger the flow in Teams, the URL changes. Copy the new URL from the trigger, enter it in Webhook URL, and change Who can trigger the workflow to match.
• Changing the Webhook URL of an action that signs in as an app asks for the client secret again. The field shows "Enter the client secret again when you change the webhook URL." Picking another Vault secret for the URL, or moving between Manual and Vault, counts as a change too.
• Switching from Anyone to a tenant setting asks for the app's details, because the action has none stored yet.

Teams REST API

In a rule action's configuration, the Microsoft Teams settings live under properties.teams. The action's type is teams.

Key	Description
webhookUrl	The workflow's URL, as {"source": "manual", "value": "…"} or {"source": "vault", "secretId": <id>}. A manual URL must be https on api.powerplatform.com or logic.azure.com.
channelLabel	The channel's name, shown in the console only. At most 100 characters.
whoCanTrigger	anyone, any_user_in_tenant or specific_users_in_tenant. Omitted means anyone. A response always carries it.
tenantId	The tenant's ID, or a domain name such as contoso.onmicrosoft.com. Required unless whoCanTrigger is anyone.
clientId	The app's application (client) ID, a GUID. Required unless whoCanTrigger is anyone.
clientSecret	The app's client secret, in the same shape as webhookUrl. Required unless whoCanTrigger is anyone.

With whoCanTrigger set to anyone, a request that sets tenantId, clientId or clientSecret is refused. An update that changes webhookUrl and keeps the stored clientSecret is refused too: send the client secret again.

In a rule's assignment of the action, the message lives under ruleSettings.teams:

Key	Description
messageTemplate	The text below the card's title, at most 3000 characters. Omitted or empty, the card says {{rule_name}} fired on {{resource_type}} {{resource_name}} at {{timestamp}} with severity {{severity}}., followed by {{message}}.

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, Microsoft Teams 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, and a rule's department, 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.
Department ID (Optional)	—	Freshservice only. Files the ticket under one of the account's departments: the department's ID, which Freshservice's Departments API lists with each department. Left empty, the ticket has no department. Freshdesk has no departments, so a Freshdesk action does not show the field. Don't add department_id as a custom field: Freshservice reads the department only from this setting, and refuses a ticket that names it as a custom field.
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, Microsoft Teams 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.
departmentId	Freshservice only. Optional department ID, a positive whole number as a string of digits, as for groupId. Empty means no department. Under ruleSettings.freshdesk it is refused with "must not be set for Freshdesk". Left out of answers when it is empty.
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.