Documentation Index

Fetch the complete documentation index at: https://help.nucleussec.com/llms.txt

Use this file to discover all available pages before exploring further.

ServiceNow App Troubleshooting

  • 3 minute(s) read
Prev Next

Troubleshooting

Given the flexibility for customizing the Nucleus Security app in ServiceNow, you may encounter scenarios where configuration and/or field mapping changes cause unexpected issues with ticket generation. This may include fields not being populated with values from Nucleus as expected or failed ticket creation.

This section provides an overview of tools and techniques for troubleshooting common configuration issues.

Validate Field Mappings

The Validate Mapping tool, located on the Manage Project screen, provides a number of tests you can run to check for common misconfiguration errors in your field mappings.

This is a great place to start if you are experiencing issues such as:

  • Ticket creation failures

  • Unable to preview tickets in the Nucleus UI

  • Unable to add or view comments on tickets from the Nucleus UI

  • Tickets failing to auto-close

  • Permission issues

Checking for Field Order Misconfigurations

The Field Order setting on mappings serves two purposes:

  • Controls the order in which content populates tickets and/or displays in the Nucleus UI

  • Controls the order in which fields are processed when creating and updating tickets

Field Order misconfigurations are a common cause of ticket creation failure. Several default mappings require a specific Field Order to ensure they are processed correctly, and there are conventions for how to apply Field Orders on custom mappings.

Review the Field Order values on your field mappings against the guidelines below to identify potential issues.

Default mappings for Parent/Child ticket configurations

Ensure these mappings have the following Field Order values:

  • Mapping_KeyID action: 1

  • project_id: 1

  • scan_type: 2

  • finding_number: 3

  • finding_justification_key: 1000

  • host_id: 1010

For all other Create (Parent/Child) mappings:

  • SN Object set to "Parent": Field Order must be greater than 100 and must be unique for each project. Typically set in the range of 620 to 990 to avoid conflicts with default mappings and to separate from Child mappings.

  • SN Object set to "Child": Field Order must be greater than 1020 and must be unique for each project.

Default mappings for Single ticket configurations

Ensure these mappings have the following Field Order values:

  • Mapping_KeyID action: 1

  • project_id: 1

  • scan_type: 2

  • finding_number: 3

  • rule_id: 4

For all other Create (Single) mappings:

  • SN Object set to "Single": Field Order should be greater than 1020 and must be unique for each project. To avoid conflicts with default mappings, we recommend setting values between 1140 and 1990.

Nucleus Security Application Logs

Application Logs allow you to search for errors encountered when creating, previewing, or updating tickets.

To view the application logs:

  • Navigate to All > Nucleus Security > Administration > Application Logs (15 min)

  • From here, you can sort and filter by Level, search for specific text in Message, and more

Enabling Debug Logging

By default, the Nucleus Security app is configured to capture only errors. For deeper troubleshooting, such as inspecting the payload sent from Nucleus, you may need to increase the Logging Verbosity.

Warning

Due to the verbosity of debug output, only enable debug logging in non-production environments unless directed to do so by Nucleus Support.

Use the following steps to enable debug logging:

  • Navigate to All > Nucleus Security > Configuration Properties

  • Edit the record and enable (check) the Enable Debug option

  • Select Debug for Logging Verbosity

  • Click Save

Using Application Logs to Troubleshoot Field Mappings

If one or more of your field mappings is not correctly populating tickets, you can use the Application Logs to inspect the payload sent from Nucleus. This helps identify configuration issues and provides visibility into all available fields.

To inspect the payload:

  • Enable debug logging in the Nucleus Security app (see above)

  • In Nucleus, create a ticket manually or using a ticketing rule

  • In ServiceNow, navigate to All > Nucleus Security > Administration > Application Logs (15 min)

  • Search the Message field for entries containing the string "DoubleCreate"

  • Locate the most recent entry containing a body that begins with "{CMDB CI..."

  • This log entry contains the full payload sent from Nucleus to the Nucleus Security app in ServiceNow when creating tickets. Copy/pasting this into a tool for viewing JSON allows you to inspect the field names and values being passed and compare them to Field Mappings to identify misconfigurations.

  • In the payload, top-level attributes represent information about the finding as a whole, and are most commonly used to populate Single ticket mappings or Parent ticket mappings in parent/child configurations:

  • Finding References are nested under the finding_references node and vary by scan source

  • Finding References also represent finding level information and are found nested below the finding_referencesnode. These attributes will vary based on what information Nucleus receives from the scan source:

  • Instance-level attributes are nested below the asset_info node, and contain additional data specific to a given asset the vulnerability was detected on: