ServiceNow
The RegScale ServiceNow integration provides bidirectional synchronization between your ServiceNow instance and RegScale. It keeps incidents, change requests, cases, attachments, and work notes aligned across both systems so that ITSM activity in ServiceNow becomes compliance evidence in RegScale without manual re-entry.
What Gets Synchronized
| ServiceNow record | ServiceNow table | RegScale record | Direction |
|---|---|---|---|
| Incident | incident | Issue | Bidirectional |
| Change Request | change_request | Change | Bidirectional |
| Case (CSM) | sn_customerservice_case | Issue | Bidirectional |
| Attachment | sys_attachment | File | Bidirectional |
| Work Note | sys_journal_field | Issue description | ServiceNow to RegScale only |
All synchronization is scoped to a single RegScale parent record — by default a Security Plan.
Prerequisites
Before running any command you need:
- A ServiceNow instance URL, in the form
https://yourinstance.service-now.com. - A ServiceNow service account with permission to read and write the tables you intend to sync. At minimum this means create and update rights on
incident; addchange_request,sn_customerservice_case, andsys_attachmentas needed. - A RegScale account and API token. Run
regscale loginto authenticate. Tokens are valid for 24 hours. - The RegScale Security Plan ID you want to sync against.
Case synchronization requires CSM
The
sync_casescommand reads thesn_customerservice_casetable, which only exists if the ServiceNow Customer Service Management plugin is installed. Case sync is disabled by default and must be explicitly enabled withsnowCaseSyncEnabled: true.
Tagging and the label_entry ACL
label_entry ACLRegScale links ServiceNow records back to RegScale records using ServiceNow labels. Tags follow the pattern regscale-REGSCALE_MODULE-REGSCALE_ID.
For tagging to work, the service account needs write access to the table and table_key columns on the label_entry table. ServiceNow restricts these by default. A ServiceNow administrator can apply the label_entry_update_acls.xml update set from the RegScale community GitHub repository, or grant the equivalent ACLs manually.
If you do not need tag-based filtering, set snowTagOnlyLinked: false and the integration will process records without relying on labels.
Configuration
All settings live in init.yaml. Every key can also be supplied as an environment variable using its UPPER_SNAKE_CASE equivalent — snowUrl becomes SNOW_URL, snowUserName becomes SNOW_USER_NAME, and so on. Environment variables take precedence over init.yaml.
Minimum Configuration
domain: https://yourcompany.regscale.com
token: <your RegScale bearer token>
userId: <your RegScale user id>
snowUrl: https://yourinstance.service-now.com
snowUserName: regscale.service
snowPassword: <service account password>
Keep credentials out of source control
snowPasswordandtokenare secrets. Prefer environment variables (SNOW_PASSWORD,REGSCALE_TOKEN) over committing them toinit.yamlin a shared repository.
Connection Settings
| Key | Default | Description |
|---|---|---|
snowUrl | (required) | ServiceNow instance base URL |
snowUserName | (required) | Service account username |
snowPassword | (required) | Service account password |
snowApiVersion | v2 | ServiceNow REST API version |
snowUseSdk | false | Use the PySNC SDK instead of raw REST calls |
snowTimeout | 30 | Request timeout in seconds |
snowVerifySslis deprecatedThis key is no longer read. Use the top-level
sslVerifysetting to control TLS certificate verification for all integrations.
Sync Behavior
| Key | Default | Description |
|---|---|---|
snowSyncDirection | bidirectional | Default direction: bidirectional, to_snow, or from_snow |
snowIncidentSyncEnabled | true | Enable incident synchronization |
snowChangeSyncEnabled | true | Enable change request synchronization |
snowCaseSyncEnabled | false | Enable case synchronization (requires CSM) |
snowAttachmentSyncEnabled | true | Enable bidirectional attachment synchronization |
snowWorkNotesSyncEnabled | true | Enable work notes synchronization |
snowTagName | RegScale | Label name used to identify RegScale-linked records |
snowTagOnlyLinked | false | Only sync ServiceNow records carrying the RegScale tag |
snowChangeDaysBack | 30 | How far back to look for change requests |
Defaults for New Incidents
| Key | Default | Description |
|---|---|---|
snowDefaultAssignmentGroup | (empty) | Assignment group applied to incidents the CLI creates |
snowDefaultUrgency | Medium | Urgency for new incidents: High, Medium, or Low |
snowDefaultPriority | 3 | Priority for new incidents, 1 through 5 |
Assignment group values are case sensitive
snowDefaultAssignmentGroupaccepts either the group name or itssys_id. If you supply a name, it must match the ServiceNow record exactly, including capitalization.
Table Overrides
Set these only if your instance uses non-standard table names or a scoped application.
| Key | Default |
|---|---|
snowIncidentTable | incident |
snowChangeTable | change_request |
snowCaseTable | sn_customerservice_case |
snowAttachmentTable | sys_attachment |
snowWorkNotesTable | sys_journal_field |
snowUserGroupTable | sys_user_group |
snowLabelTable | label |
Performance Tuning
| Key | Default | Description |
|---|---|---|
snowBatchSize | 100 | Records per bulk operation |
snowPageLimit | 500 | Maximum records returned per API page |
snowMaxWorkers | 10 | Maximum concurrent worker threads |
Query Filters
These append an additional ServiceNow sysparm_query to the records the CLI retrieves.
| Key | Default | Description |
|---|---|---|
snowIncidentFilter | (empty) | Extra query filter for incidents |
snowChangeFilter | (empty) | Extra query filter for change requests |
snowCaseFilter | (empty) | Extra query filter for cases |
For example, to sync only incidents assigned to a specific group:
snowIncidentFilter: assignment_group.name=Security Operations
Filters silently narrow your evidence set
A filter that is too restrictive causes records to be excluded from the sync with only a warning in the log. If you use filters for compliance evidence collection, document what each one excludes.
Custom Field Mapping
Map additional ServiceNow fields to RegScale fields using JSON objects. Each record type has its own mapping.
| Key | Applies to |
|---|---|
snowCustomFields | Incidents |
snowChangeCustomFields | Change requests |
snowCaseCustomFields | Cases |
serviceNow:
customFields:
u_business_service: Enterprise Platform
u_cost_center: CC-4417
Commands
All commands are under the regscale servicenow group.
regscale servicenow --help
test_connection
test_connectionValidates your configuration and confirms the CLI can reach your ServiceNow instance. Run this first when setting up.
regscale servicenow test_connection
On success it reports the instance hostname and whether the SDK mode is active.
inventory
inventoryChecks which standard ServiceNow tables the service account can actually read. Use this to diagnose permission problems before running a full sync.
regscale servicenow inventory
Each table is reported as Available, Empty, or Not accessible.
sync_incidents
sync_incidentsSynchronizes ServiceNow incidents with RegScale issues, creating records on either side as needed and updating those that already exist.
| Flag | Default | Description |
|---|---|---|
--regscale_ssp_id | (required) | RegScale Security Plan ID |
--direction | from config | bidirectional, to_snow, or from_snow |
--sync-attachments / --no-attachments | --sync-attachments | Whether to sync attachments |
--parent-module | securityplans | RegScale parent module |
regscale servicenow sync_incidents --regscale_ssp_id 5 --direction bidirectional
sync_changes
sync_changesSynchronizes ServiceNow change requests with the RegScale Change module, including the full set of change management fields.
| Flag | Default | Description |
|---|---|---|
--regscale_ssp_id | (required) | RegScale Security Plan ID |
--direction | from config | bidirectional, to_snow, or from_snow |
--days-back | 30 | How many days back to look for changes |
--parent-module | securityplans | RegScale parent module |
regscale servicenow sync_changes --regscale_ssp_id 5 --days-back 90
sync_cases
sync_casesSynchronizes ServiceNow CSM cases with RegScale issues. Requires the CSM plugin and snowCaseSyncEnabled: true.
| Flag | Default | Description |
|---|---|---|
--regscale_ssp_id | (required) | RegScale Security Plan ID |
--direction | from config | bidirectional, to_snow, or from_snow |
--sync-attachments / --no-attachments | --sync-attachments | Whether to sync attachments |
--parent-module | securityplans | RegScale parent module |
regscale servicenow sync_cases --regscale_ssp_id 5
sync_all
sync_allRuns every enabled synchronization in one pass. This is the command to schedule for routine operation.
| Flag | Default | Description |
|---|---|---|
--regscale_ssp_id | (required) | RegScale Security Plan ID |
--direction | from config | bidirectional, to_snow, or from_snow |
--incidents / --no-incidents | --incidents | Include incidents |
--changes / --no-changes | --changes | Include change requests |
--cases / --no-cases | --no-cases | Include cases |
--attachments / --no-attachments | --attachments | Include attachments |
--parent-module | securityplans | RegScale parent module |
regscale servicenow sync_all --regscale_ssp_id 5 --cases
sync_work_notes
sync_work_notesPulls work notes from ServiceNow and appends them to the matching RegScale issue descriptions with HTML formatting. This is a one-way sync from ServiceNow into RegScale.
| Flag | Default | Description |
|---|---|---|
--regscale_ssp_id | (required) | RegScale Security Plan ID |
--parent-module | securityplans | RegScale parent module |
regscale servicenow sync_work_notes --regscale_ssp_id 5
Legacy Commands
These remain available for backward compatibility with existing scripts. New automation should use the commands above.
| Legacy command | Replacement |
|---|---|
issues | sync_incidents --direction to_snow |
issues_and_attachments | sync_incidents --direction bidirectional |
issues still accepts --snow-assignment-group and --snow-incident-type, but these values are no longer used for routing. Assignment is controlled by snowDefaultAssignmentGroup in init.yaml. The CLI prints a notice when it receives them.
issues_and_attachments accepts --sync-all-incidents to process every incident rather than only tagged ones. This is equivalent to setting snowTagOnlyLinked: false.
Flag names changed for some options
--parent-moduleuses hyphens and replaces the older--regscale_module. The Security Plan ID flag still accepts--regscale_ssp_id,--regscale_id,--id, and-id. Update any scripts that pass--regscale_moduleor underscore-separated ServiceNow flags.
Change Request Field Mapping
sync_changes maps the following fields in both directions.
| ServiceNow field | RegScale Change field |
|---|---|
number | externalId |
short_description | title |
description | description |
reason | reason |
justification | justification |
type | changeType |
state | status |
approval | approvalStatus |
risk | riskLevel |
priority | priority |
implementation_plan | implementationPlan |
backout_plan | rollbackPlan |
test_plan | testPlan |
start_date / end_date | scheduledStart / scheduledEnd |
work_start / work_end | actualStart / actualEnd |
opened_by / opened_at | createdBy / dateCreated |
closed_at / close_notes | dateCompleted / closeNotes |
assigned_to | assignedTo |
Change types map as standard, normal, and emergency. Priority maps from the ServiceNow 1–5 scale to RegScale's Critical, High, Medium, and Low values.
Configuration Management Evidence Coverage
Organizations pursuing FedRAMP, RMF, or similar authorizations frequently use this integration to bring change management records into their compliance program. This section describes what the change synchronization contributes as evidence.
The integration transports and retains records about changes. It does not approve, gate, or enforce changes — those functions remain in ServiceNow. Control satisfaction requires a documented process, enforcement, and records; this integration automates the records and evidence portion.
| Control area | What the sync contributes |
|---|---|
| Documenting proposed changes | reason, justification, description, and changeType are captured as first-class fields, with the ServiceNow change number retained as externalId for traceability. |
| Documenting change decisions | approvalStatus records the approval decision, closeNotes the disposition rationale, and dateCompleted the timestamp. |
| Implementing approved changes | implementationPlan alongside actualStart and actualEnd demonstrates that the approved change is what was executed, and when. rollbackPlan evidences that a reversal path was defined. |
| Retaining change records | Records persist in the RegScale Change module scoped to the Security Plan, independent of ServiceNow retention policy, with a clean line back to the originating change ticket. |
| Testing and validating changes | testPlan carries the intended testing approach. Test results are not part of the mapping and must be evidenced separately. |
| Change review and oversight | approvalStatus reflects the board decision and the sync gives reviewers a consolidated view. Board membership, quorum, and review workflow are not modeled and require separate process documentation. |
| Continuous monitoring | Change records landing under the Security Plan help keep authorization boundary documentation current between assessments. |
What This Integration Does Not Provide
- Security impact analysis. There is no dedicated impact analysis field in the standard mapping.
riskmaps toriskLevel, which is a coarse risk band rather than an analysis artifact. If your instance records impact analysis in a custom field, map it throughsnowChangeCustomFields. - Approval chain verification. The integration copies the value of the
approvalfield. It does not validate who approved the change or on what basis. The strength of this evidence depends entirely on the ServiceNow workflow behind that field. - Access restrictions for change. Enforcement is handled by ServiceNow and RegScale role-based access control, not by the CLI.
Confirm control applicability against your baseline
Which configuration management controls and enhancements apply depends on your target baseline. Work with your assessor to confirm applicability before relying on this integration as an evidence source.
Scheduling Routine Synchronization
Commands can be chained in any shell. The example below uses Bash, but PowerShell and Python work equally well.
Create regscaleScheduler.sh:
#!/bin/sh
regscale login
regscale servicenow sync_all --regscale_ssp_id 5 --direction bidirectional
Run it with:
. regscaleScheduler.sh
Commands execute sequentially, so you can combine ServiceNow synchronization with other RegScale CLI operations in the same script.
Updated 6 days ago