Skip to content

Commit c37eacf

Browse files
sdsubhajitdasrajlearner17
sdsubhajitdas
and
rajlearner17
committed
Add guide for discovering ServiceNow custom tables in Guardrails (#331)
Co-authored-by: raj <raj@turbot.com>
1 parent a1f4b58 commit c37eacf

File tree

9 files changed

+250
-24
lines changed

9 files changed

+250
-24
lines changed

‎docs/guides/servicenow/discovery-servicenow-custom-tables/business-rule-policy.png

96.2 KB
Loading

‎docs/guides/servicenow/discovery-servicenow-custom-tables/index copy.md

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
---
2+
title: Discover ServiceNow Custom Tables
3+
sidebar_label: Discover ServiceNow Custom Tables
4+
---
5+
This guide explains how to discover and manage records from custom ServiceNow tables in Turbot Guardrails.
6+
7+
## What you'll learn
8+
9+
- How to enable discovery of custom ServiceNow tables in Guardrails
10+
- How to configure which tables to discover and filter records
11+
- How to set up event-driven updates for custom table records
12+
13+
## Time to complete
14+
15+
10-15 minutes
16+
17+
## Prerequisites
18+
19+
Before starting this guide, make sure you have:
20+
21+
- [Imported your ServiceNow instance into Guardrails](/guardrails/docs/guides/servicenow/import-servicenow-instance)
22+
- Installed the `@turbot/servicenow-custom` mod in your workspace
23+
24+
# Discovering ServiceNow Custom Tables
25+
26+
Turbot Guardrails can discover and manage records from any specified ServiceNow table, extending visibility beyond the pre-configured Application, Cost Center, and User tables. This allows you to bring data from your custom or other standard ServiceNow tables into Guardrails as `ServiceNow > Custom > Record` resources.
27+
28+
## Prerequisites
29+
30+
### Associate your ServiceNow instance to Turbot Guardrails
31+
32+
Before you get started, ensure you have completed the steps in the [Importing a ServiceNow instance into Guardrails](/guardrails/docs/guides/servicenow/import-servicenow-instance) guide to associate your ServiceNow instance with Turbot Guardrails.
33+
34+
### Turbot Guardrails Mod Installation
35+
36+
The `@turbot/servicenow-custom` mod must be installed in your Guardrails workspace. This mod provides the necessary resource types, policies, and controls for discovering custom table records. Ensure it is installed and the mod's `Installed` control is in the `OK` state.
37+
38+
## Enabling Custom Table Discovery
39+
40+
To enable the discovery of records from specific ServiceNow tables, you need to configure the relevant policies. The primary policies involved are:
41+
42+
- `ServiceNow > Custom > Table > CMDB`
43+
- Enables the discovery mechanism for custom tables.
44+
- Set this policy to `Enforce: Enabled` at the scope of your ServiceNow instance resource or higher.
45+
- `ServiceNow > Custom > Table > CMDB > Tables`
46+
- Specifies the list of ServiceNow table names you want Guardrails to discover records from.
47+
- Provide a YAML list of table names (e.g., `["u_custom_table", "cmdb_ci_storage_volume"]`).
48+
- Defaults to an empty list `[]`.
49+
- > [!IMPORTANT]
50+
> Removing a table name from this list will result in the deletion of the corresponding `ServiceNow > Custom > Table` resource and all its child `ServiceNow > Custom > Record` resources from the Guardrails CMDB.
51+
- `ServiceNow > Custom > Record > CMDB > Query`
52+
- Allows filtering of records discovered from the specified tables using a ServiceNow encoded query string.
53+
- Paste the encoded query string as the policy value.
54+
- Defaults to `""` (empty string), meaning no filter is applied.
55+
- `ServiceNow > Custom > Record > CMDB > Title`
56+
- Specifies the data key(s) used to retrieve the title for discovered `ServiceNow > Custom > Record` resources in Guardrails.
57+
- Provide an array of strings representing field names in order of preference (e.g., `["name", "display_name", "sys_id"]`). Guardrails uses the first field in the list that contains a non-empty value.
58+
- This allows for fallback options if preferred fields are missing or empty.
59+
- Defaults to `["name", "display_value", "display_name", "title", "label", "short_description", "number", "sys_name", "sys_title", "sys_id"]`.
60+
- You can customize this list by creating a new policy setting.
61+
62+
### Business Rule for Event-Driven Updates (Optional)
63+
64+
Similar to the pre-configured table sync, you can enable event-driven updates for discovered custom tables:
65+
66+
- `ServiceNow > Custom > Table > Business Rule`
67+
- Configures ServiceNow Business Rules for event handling of record changes (new, updated, deleted) in the discovered tables.
68+
- Set to `Enforce: Configured` to enable automatic setup and management.
69+
- Requires `ServiceNow > Config > System Properties` to be set to `Enforce: Configured` as described in the [ServiceNow sync prerequisites](/guardrails/docs/guides/servicenow/servicenow-to-guardrails-sync#prerequisites).
70+
- `ServiceNow > Custom > Table > Business Rule > Name`
71+
- Allows customization of the Business Rule name.
72+
73+
## Example: Discovering the Server Table (`cmdb_ci_server`)
74+
75+
To discover records from the standard ServiceNow Server table `cmdb_ci_server`:
76+
77+
1. Set `ServiceNow > Custom > Table > CMDB` to `Enforce: Enabled`.
78+
2. Set `ServiceNow > Custom > Table > CMDB > Tables` to:
79+
```yaml
80+
- cmdb_ci_server
81+
```
82+
3. (Optional) To only discover active servers, set `ServiceNow > Custom > Record > CMDB > Query` to `active=true` (or the relevant field/value for server status).
83+
4. (Optional) To enable real-time updates, set `ServiceNow > Custom > Table > Business Rule` to `Enforce: Configured`.
84+
85+
Once configured, Guardrails will begin discovering records from the `cmdb_ci_server` table. These records will appear in your Guardrails inventory under the associated ServiceNow instance resource as `ServiceNow > Custom > Record` resources.
86+
87+
## Next Steps
88+
89+
- Explore the discovered `ServiceNow > Custom > Record` resources in your Guardrails inventory.
90+
- Utilize the data from these custom records in Guardrails policies and calculated policies for context-aware automation.
91+
92+
For more details on the specific policies and controls introduced, refer to the `servicenow-custom` mod changelog [[1]](https://turbot.com/guardrails/changelog/servicenow-custom-v5-0-0).
93+
94+
We want to hear from you! Join our [Slack Community](https://turbot.com/community/join) `#guardrails` channel to ask questions and share feedback.

‎docs/guides/servicenow/discovery-servicenow-custom-tables/index.md

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
---
2+
title: Discover ServiceNow Custom Tables
3+
sidebar_label: Discover ServiceNow Custom Tables
4+
---
5+
6+
# Discovering ServiceNow Custom Tables
7+
8+
In this guide, you will:
9+
10+
- Learn how to discover and manage records from custom ServiceNow tables in Turbot Guardrails
11+
- Configure table discovery, filtering, and record title display settings
12+
- Set up optional business rules for custom table management
13+
14+
Turbot Guardrails can discover and manage records from any specified ServiceNow table, extending visibility beyond the pre-configured Application, Cost Center, and User tables. This allows you to bring data from your custom or other standard ServiceNow tables into Guardrails as `ServiceNow > Custom > Record` resources.
15+
16+
## Prerequisites
17+
18+
- An active ServiceNow instance integrated with Turbot Guardrails following the [Importing a ServiceNow instance into Guardrails](/guardrails/docs/guides/servicenow/import-servicenow-instance) guide.
19+
- The `@turbot/servicenow-custom` mod installed in your Guardrails workspace. See [Install a Mod](/guardrails/docs/guides/configuring-guardrails/install-mod).
20+
- Administrator access to your ServiceNow instance.
21+
- Administrator access to your Turbot Guardrails workspace.
22+
23+
## Enabling Custom Table Discovery
24+
25+
To enable discovery of records from ServiceNow custom tables, configure the following policies:
26+
27+
### ServiceNow > Custom > Table > CMDB
28+
29+
- Enables the discovery for custom tables.
30+
- Set this policy to `Enforce: Enabled` at the scope of your ServiceNow instance resource or higher.
31+
32+
### ServiceNow > Custom > Table > CMDB > Tables
33+
34+
- Specifies the list of ServiceNow table names you want Guardrails to discover records from.
35+
- Provide a YAML list of table names e.g. `["u_custom_table", "cmdb_ci_storage_volume"]`.
36+
- Defaults to an empty list `[]`.
37+
38+
> [!IMPORTANT]
39+
> Removing a table name from this list will result in the deletion of the corresponding `ServiceNow > Custom > Table` resource and all its child `ServiceNow > Custom > Record` resources from the Guardrails CMDB.
40+
41+
## Set Optional Policies
42+
43+
The following two policies allow you to control which records are discovered and how they are displayed in Guardrails:
44+
45+
### ServiceNow > Custom > Record > CMDB > Query
46+
47+
- Allows you to refine which records are discovered by applying [ServiceNow encoded query string](https://www.servicenow.com/docs/bundle/yokohama-platform-user-interface/page/use/using-lists/concept/c_EncodedQueryStrings.html).
48+
- Useful for limiting discovery to specific records that match your criteria.
49+
- For example, filter by status, category, or any other field available in the ServiceNow table
50+
- Defaults to `""` (empty string) which means all records will be discovered.
51+
52+
### ServiceNow > Custom > Record > CMDB > Title
53+
54+
- Specifies the data key(s) used to retrieve the title for discovered `ServiceNow > Custom > Record` resources in Guardrails.
55+
- Provide an array of strings representing field names in order of preference e.g. `["name", "display_name", "sys_id"]`. Guardrails uses the first field in the list that contains a non-empty value.
56+
- This allows for fallback options if preferred fields are missing or empty.
57+
- Defaults to `["name", "display_value", "display_name", "title", "label", "short_description", "number", "sys_name", "sys_title", "sys_id"]`.
58+
- Customize by creating a new policy setting.
59+
60+
<!-- ### Business Rule for Event-Driven Updates (Optional) -->
61+
62+
## (Optional) Configure Real-time Business Rules
63+
64+
To enable real-time updates when records change in ServiceNow, you can configure Business Rules. This allows Guardrails to automatically sync changes as they happen in ServiceNow.
65+
66+
Before configuring Business Rules, ensure you have:
67+
68+
1. Set `ServiceNow > Config > System Properties` to `Enforce: Configured` as described in the [ServiceNow sync prerequisites](/guardrails/docs/guides/servicenow/servicenow-to-guardrails-sync#prerequisites).
69+
2. Administrator access to create Business Rules in ServiceNow
70+
71+
### ServiceNow > Custom > Table > Business Rule
72+
73+
Configures ServiceNow Business Rules for real-time event handling of record changes (new, updated, deleted) in the discovered tables.
74+
75+
- Set to `Enforce: Configured` to enable automatic setup and management.
76+
77+
78+
### ServiceNow > Custom > Table > Business Rule > Name
79+
80+
- Allows customization of the Business Rule name.
81+
82+
## Example: Discovering the Server Table
83+
84+
To discover records from the standard ServiceNow Server table `cmdb_ci_server`, follow these steps:
85+
86+
1. Set `ServiceNow > Custom > Table > CMDB` to `Enforce: Enabled`.
87+
2. Set `ServiceNow > Custom > Table > CMDB > Tables` with yaml value as `- cmdb_ci_server`
88+
89+
![ServiceNow Discovery Policy Settings](/images/docs/guardrails/guides/servicenow/discovery-servicenow-custom-tables/policy-setting.png)
90+
91+
3. (Optional) To only discover active servers, set `ServiceNow > Custom > Record > CMDB > Query` to `active=true` (or the relevant field/value for server status).
92+
4. (Optional) To enable real-time updates, set `ServiceNow > Custom > Table > Business Rule` to `Enforce: Configured`.
93+
94+
![ServiceNow Business Rule Setting](/images/docs/guardrails/guides/servicenow/discovery-servicenow-custom-tables/business-rule-policy.png)
95+
96+
Guardrails will now discover records from `cmdb_ci_server`. These records will appear in your Guardrails inventory under the ServiceNow instance resource as `ServiceNow > Custom > Record` resources.
97+
98+
99+
## Next Steps
100+
101+
Please see the following resources to learn more about ServiceNow integrations:
102+
103+
- [Enable ServiceNow to Guardrails Sync](/guardrails/docs/guides/servicenow/servicenow-to-guardrails-sync)
104+
- [Enable Guardrails to ServiceNow Sync](/guardrails/docs/guides/servicenow/guardrails-to-servicenow-sync)
105+
106+
## Troubleshooting
107+
108+
| Issue | Description | Guide |
109+
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
110+
| Common errors | Common issues that may prevent controls from running include network connectivity problems, permission issues, and API rate limits. These can cause controls to enter an error state. | Refer to [Common Troubleshooting](/guardrails/docs/guides/troubleshooting) for detailed resolution steps. |
111+
| Further Assistance | If you encounter further issues with Calculated Policies, please open a ticket with us and attach the relevant information to assist you more efficiently. | [Open Support Ticket](https://support.turbot.com) |
112+
| Community Support | We want to hear from you! Join our [Slack Community](https://turbot.com/community/join) `#guardrails` channel to ask questions and share feedback. | [Join Slack Community](https://turbot.com/community/join) |

‎docs/guides/servicenow/discovery-servicenow-custom-tables/policy-setting.png

149 KB
Loading

‎docs/guides/servicenow/guardrails-to-servicenow-sync/index.md

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,9 @@
11
---
2-
title: "Enable Guardrails sync to ServiceNow"
3-
template: Documentation
4-
nav:
5-
title: "Enable Guardrails sync to ServiceNow"
6-
order: 20
2+
title: Enable Guardrails to ServiceNow Sync
3+
sidebar_label: Enable Guardrails to ServiceNow Sync
74
---
85

9-
# Enable Guardrails sync to ServiceNow
6+
# Enable Guardrails to ServiceNow Sync
107

118
## Prerequisites
129

‎docs/guides/servicenow/import-servicenow-instance/index.md

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,9 @@
11
---
2-
title: "Importing a ServiceNow instance into Guardrails"
3-
template: Documentation
4-
nav:
5-
title: "Importing Accounts"
6-
order: 20
2+
title: Import ServiceNow Instance
3+
sidebar_label: Import ServiceNow Instance
74
---
85

9-
# Importing a ServiceNow instance into Guardrails
6+
# Importing a ServiceNow Instance in Guardrails
107

118
## Prerequisites to import a ServiceNow instance
129

‎docs/guides/servicenow/index.md

Lines changed: 27 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@ Turbot Guardrails is deeply integrated with [ServiceNow](https://servicenow.com)
1111

1212
1. Continuously sync ServiceNow resources to Turbot Guardrails
1313
2. Continuously sync cloud resources with Turbot Guardrails to ServiceNow
14+
3. Discover and manage records from any ServiceNow table
15+
1416

1517
## 1. Continuously sync ServiceNow resources to Turbot Guardrails
1618
ServiceNow resources such Applications, Cost Centers, Users, etc tables can sync to Turbot Guardrails. This integration bridges the gap between your business context with your cloud & security controls.
@@ -29,7 +31,7 @@ Syncing ServiceNow CMDB data brings critical context to your cloud resources in
2931
* And many other cloud and security automation use cases
3032

3133
**To get started:**
32-
* [Import a ServiceNow Instance](https://turbot.com/guardrails/docs/guides/servicenow/import-servicenow-instance) into a Guardrails Folder.
34+
* [Import a ServiceNow Instance](/guardrails/docs/guides/servicenow/import-servicenow-instance) into a Guardrails Folder.
3335
* [Enable ServiceNow sync to Guardrails](https://turbot.com/guardrails/docs/guides/servicenow/servicenow-to-guardrails-sync) to configure real-time syncing.
3436

3537
Additional context about the feature is in the announcement post [ServiceNow + Guardrails: Context-aware cloud & security automation](https://turbot.com/guardrails/blog/2023/12/context-aware-guardrails-servicenow-integration).
@@ -50,8 +52,30 @@ Continuously syncing your cloud resources into ServiceNow enhances the CMDB into
5052
* Enrich context: surface tags as key resource data.
5153

5254
**To get started:**
53-
* [Import a ServiceNow Instance](https://turbot.com/guardrails/docs/guides/servicenow/import-servicenow-instance) into a Guardrails Folder.
54-
* [Enable Guardrails sync to ServiceNow](https://turbot.com/guardrails/docs/guides/servicenow/guardrails-to-servicenow-sync) to configure real-time syncing.
55+
* [Import a ServiceNow Instance](/guardrails/docs/guides/servicenow/import-servicenow-instance) into a Guardrails Folder.
56+
* [Enable Guardrails sync to ServiceNow](/guardrails/docs/guides/servicenow/guardrails-to-servicenow-sync) to configure real-time syncing.
57+
58+
## 3. Discover and manage records from any ServiceNow table
59+
60+
Guardrails can discover and manage records from any ServiceNow table, extending visibility beyond the pre-configured Application, Cost Center, and User tables. This allows you to bring data from your custom or other standard ServiceNow tables into Guardrails as ServiceNow Custom Record resources.
61+
62+
When enabled, Guardrails configures and manages:
63+
1. Guardrails provides the ServiceNow Custom mod, with policies and controls to support discovering and managing any ServiceNow table
64+
2. Event handlers (Business Rules) for each discovered table to handle real-time updates as records are created, modified, and deleted
65+
3. Audit trail of all activity on your discovered tables to see what happened, who made the change, when it occurred, and what configuration differences were made
66+
67+
Discovering custom tables enhances your cloud and security automation capabilities:
68+
69+
* Extend visibility to any ServiceNow table data
70+
* Filter which records to discover using ServiceNow queries
71+
* Configure how records are displayed in Guardrails
72+
* Enable real-time updates through Business Rules
73+
74+
**To get started:**
75+
76+
* [Import a ServiceNow Instance](/guardrails/docs/guides/servicenow/import-servicenow-instance) into a Guardrails Folder
77+
* [Discover ServiceNow Custom Tables](/guardrails/docs/guides/servicenow/discovery-servicenow-custom-tables) to configure table discovery and record management
78+
5579

5680
Additional context about the feature is in the announcement post [Continuous Cloud CMDB Sync with ServiceNow & Turbot Guardrails](https://turbot.com/guardrails/blog/2023/12/cmdb-sync-guardrails-servicenow-integration).
5781

0 commit comments

Comments
 (0)