Operational status rules determine how the statuses of individual elements affect the overall operational status of the parent service.
These rules are stored in Salesforce in the Operational Status Rules field on the service record.
Rules are written using Groovy script syntax. The syntax supports Java-style comments, including both single-line (//) and multi-line (/* */) formats. It is strongly recommended to include comments to document each rule for future maintenance and clarity.
Return Values
The script must return one of the following values, corresponding to the service’s operational status values in Salesforce:
- UP — The service is fully operational (‘Up’).
- DOWN — The service is not available (‘Down’).
- HAS_ISSUES — The service is available but experiencing issues, e.g. long response times (‘Has Issues’)
- UNKNOWN — The service status could not be determined (e.g., no rules matched). This status is not synchronized to Salesforce.
Rule Structure
Regardless of the specific logic used, every rule script follows the same structure:
user-defined conditions
simpleCondition() ← final call returning the status value (the last line of the script)The simpleCondition() function is a built-in function that takes a single condition object as an argument. A condition object includes the following properties:
| Property | Description |
|---|---|
| Property | Description |
| status | The status to return when the condition is met. |
| unknown | Status to return when no rules match. |
| condition | An array of condition definitions. All conditions must be met for the rule to apply. |
Each condition object inside the array has the following properties:
| Property | Description |
|---|---|
| pattern | A regular expression for matching element names (Name field in Salesforce), selecting which elements to evaluate in the condition. These may be either sets [E1|E2|E3] or regular expressions such as [E*]. |
| status | A set of required element statuses (e.g., [DOWN, HAS_ISSUES]). |
| count | A numeric value indicating how many elements must be in the required statuses. Positive values represent “greater than or equal,” while negative values represent “less than or equal.” |
| percent | An alternative to count. Represents the percentage of matching elements that must meet the condition. Only one of count or percent can be used per condition. As with count, positive and negative values indicate “greater than or equal” or “less than or equal,” respectively. |
Example 1: Business Internet Service
Let’s assume a business internet service is built for redundancy, composed of the following elements:
B-INTERNET ← Service name
PRI ← Primary DIA connection
SEC-1 ← Secondary broadband connection
SEC-2 ← Secondary broadband connection
The service status should be calculated as follows:
- Up — The primary connection is Up and at least one secondary connection is Up.
- Has Issues — The primary connection is Down but at least one secondary connection is working.
- Down — All PRI, SEC-1 and SEC-2 are down.
The corresponding Operational Status Rule can be written as:
isUp = [
status: UP,
unknown: UNKNOWN, // No mapping provided for the unknown status
condition: [
[ pattern: ‘PRI’ , count: 1, status: [UP] ],
[ pattern: ‘SEC-1|SEC-2' percent: 1/2, status: [UP] ]
]
];
simpleCondition(isUp)Example 2: DNS Service
A DNS service is built using three independent DNS servers as follows:
DNS Service
DNS-1
DNS-1
DNS-2
The service status should be calculated as follows:
- Up — At least to out of three DNS servers are working.
- Has Issues — Only one server is working.
- Down — All servers are down.
The corresponding Operational Status Rule can be written as:
// The first condition checks if there are at least two DNS servers in ‘Up’ status:
isUp = [
status: UP,
condition: [
[ pattern: ‘DNS-1|DNS-2|DNS-3’ , count: 2, status: [UP]]
]
];
// In the second condition it is already known that there is no more than one server in the ‘Up’ status. Therefore, it is enough to check if there is no less than one server in the ‘Up’ status
hasIssues = [
status: HAS_ISSUES,
condition: [
[ pattern: ‘DNS-1|DNS-2|DNS-3’ , count: 1, status: [UP]]
]
];
// From previous conditions we already know there is no server in the ‘Up’ status so the entire service is ‘Down’:
isDown = [
status: DOWN
];
// The following call combines all three conditions:
simpleCondition(isUp)|simpleCondition(hasIssues)|simpleCondition(isDown)
Example 3: WiFi Service
A WiFi service consists of five Access Points (APs): one main controller (AP-1) and four regular APs (AP-2 through AP-5) that are connected to and dependent on the main controller:
WIFI Service
AP-1 ← main controller
AP-2 ← regular AP
AP-3 ← regular AP
AP-4 ← regular AP
AP-5 ← regular AP
The service status should be calculated as follows:
- Up — When the main controller (AP-1) is Up and at least 3 out of 4 regular APs (75%) are also Up. One AP may be Down, and the service is still considered fully operational.
- Down — When the main controller (AP-1) is Down, or when 2 or more regular APs (50% or more) are Down.
- Has Issues — Any other combination not covered above.
This approach above — where only Up and Down are explicitly defined and all other cases fall back to Has Issues — is a recommended pattern.
The corresponding Operational Status Rule can be written as:
// This is first condition is where we check that the AP-1 and 3/4 of regular APs are are ‘Up’:
isUp = [
status: UP,
condition: [
[ pattern: ‘AP-1’ , count: 1, status: [UP]].
[ pattern: ‘AP-2|AP-3|AP-4|AP-5’ , percentage: 3/4, status: [UP]]
]
];
// Check that AP-1 is ‘Down’:
isDown1 = [
status: DOWN
condition: [
[ pattern: ‘AP-1’ , count: 1, status: [DOWN]]
]
];
// Now, check if two or more regular APs are ‘Down’:
isDown2 = [
status: DOWN,
condition: [
[ pattern: ‘AP-2|AP-3|AP-4|AP-5’, count: 2, status: [DOWN] ]
}
];
// All other cases are treated as ‘Has Issues’:
isDown = [
status: HAS_ISSUES
];
simpleCondition(isUp) |
simpleCondition(isDown1) |
simpleCondition(isDown2) |
simpleCondition(hasIssues)
To support more complex rules — where the returned status depends on multiple conditions — Groovy’s conditional expression syntax can be applied:
simpleCondition(isUp)?: simpleCondition(isDown) ?: simpleCondition(isHasIssues) The rule above is interpreted as follows: the result is returned from the first simpleCondition() function that matches its condition and returns a non-null status value.
