Skip to main content

ServiceNow

ServiceNow is an enterprise IT Service Management (ITSM) platform that helps organizations manage digital workflows for IT operations. It provides a comprehensive suite of tools for incident management, problem tracking, change management, configuration management database (CMDB), knowledge base, and service catalog. ServiceNow enables IT teams to streamline service delivery, automate workflows, and maintain a complete view of their IT infrastructure and services.

Authentication Types​

ServiceNow supports 2 authentication methods:

  • OAuth 2.0 - Secure, token-based authentication with automatic token refresh.

    • Pros: Most secure method, supports token refresh, follows modern standards, recommended for production
    • Cons: More complex initial setup, requires creating OAuth application in ServiceNow
    • Best for: Production deployments, enterprise integrations, applications requiring long-term access

  • Basic Authentication - Simple username and password authentication.

    • Pros: Very simple to set up, no app registration needed, works immediately
    • Cons: Less secure, credentials sent with each request, no automatic expiration
    • Best for: Development/testing, personal use, quick prototypes, single-user scenarios

General Settings​

Before using the connector, you need to configure:

  • ServiceNow Instance URL - Your ServiceNow instance URL (e.g., https://dev12345.service-now.com or https://yourcompany.service-now.com)
tip

You can find your instance URL in your browser's address bar when logged into ServiceNow. Copy the entire URL including https:// but excluding any path after .com. For example:

  • URL in browser: https://dev12345.service-now.com/now/nav/ui/home → Instance URL: https://dev12345.service-now.com
  • URL in browser: https://acmecorp.service-now.com/incident_list.do → Instance URL: https://acmecorp.service-now.com

Setting up OAuth​

To use ServiceNow with OAuth 2.0, you need to register an OAuth application in your ServiceNow instance.

1. Navigate to Application Registry​

  1. Log in to your ServiceNow instance as an administrator

  2. In the navigation filter (top-left search), type Application Registry

  3. Click System OAuth → Application Registry

2. Create OAuth API Endpoint​

  1. Click New to create a new application

  2. Select Create an OAuth API endpoint for external clients

  3. Fill in the application details:

    • Name: Enter a descriptive name (e.g., "Webrix Integration")
    • Client ID: Leave blank to auto-generate, or provide your own
    • Client Secret: Leave blank to auto-generate
    • Redirect URL: Copy the redirect URL from Webrix platform and paste it here
    • Refresh Token Lifespan: Leave default or adjust as needed (e.g., 8640000 for 100 days)
    • Access Token Lifespan: Leave default or adjust as needed (e.g., 1800 for 30 minutes)

  4. Click Submit

3. Configure Application Settings​

  1. After creation, open the OAuth application record you just created

  2. Scroll down to verify these settings:

    • Active: Checked
    • Accessible from: All application scopes (or specific scope if needed)

  3. Note down the Client ID and Client Secret (you may need to reveal the secret)

    warning

    Keep your Client Secret secure! Never share it publicly or commit it to version control. If compromised, regenerate it immediately in ServiceNow.

4. Configure in Webrix​

  1. In Webrix, go to Integrations → New → Built-in

  2. Select ServiceNow and click Use

  3. Under General Settings, enter your ServiceNow Instance URL (e.g., https://dev12345.service-now.com)

  4. Under Authentication Type, select OAuth

  5. Paste your Client ID from ServiceNow

  6. Paste your Client Secret from ServiceNow

  7. Click Save Changes

5. Test the Connection​

  1. After saving, click Connect to initiate the OAuth flow

  2. You'll be redirected to your ServiceNow instance to authorize the application

  3. Log in if prompted and review the permissions

  4. Click Allow to grant access

  5. You'll be redirected back to Webrix with a successful connection

Setting up Basic Authentication​

Basic Authentication is simpler but less secure. Use this for development, testing, or single-user scenarios.

1. Create a ServiceNow User Account​

You can use an existing user account or create a dedicated integration user:

  1. Log in to your ServiceNow instance as an administrator

  2. Navigate to User Administration → Users

  3. Create a new user or select an existing one

  4. Ensure the user has appropriate roles:

    • rest_api_explorer - For API access
    • itil - For ITSM tables (incidents, problems, changes)
    • Additional roles based on your needs (e.g., admin for full access)

  5. Set a strong password for the user

    warning

    Integration accounts should have strong, unique passwords and only the minimum required permissions. Consider using a dedicated service account rather than a personal user account.

2. Configure in Webrix​

  1. In Webrix, go to Integrations → New → Built-in

  2. Select ServiceNow and click Use

  3. Under General Settings, enter your ServiceNow Instance URL

  4. Under Authentication Type, select API Key (Basic Auth)

  5. Enter your ServiceNow Username in the username field

  6. Enter your ServiceNow Password in the password field

  7. Click Save Changes

3. Test the Connection​

  1. After saving, click Connect to test the connection

  2. If successful, you'll see a confirmation message

  3. The credentials are base64-encoded and sent with each request

Understanding ServiceNow Query Syntax​

Many ServiceNow tools support sysparm_query for filtering records. This uses ServiceNow's encoded query syntax:

Basic Query Operators​

  • = - Equals (e.g., state=1)
  • != - Not equals (e.g., active!=false)
  • > - Greater than (e.g., priority>3)
  • < - Less than (e.g., priority<2)
  • LIKE - Contains (e.g., short_descriptionLIKEpassword)
  • STARTSWITH - Starts with (e.g., numberSTARTSWITHINC)
  • ENDSWITH - Ends with (e.g., [email protected])
  • ISEMPTY - Field is empty (e.g., assigned_toISEMPTY)
  • ISNOTEMPTY - Field is not empty (e.g., assigned_toISNOTEMPTY)

Combining Conditions​

  • ^ - AND operator (e.g., state=1^priority=1 for new AND critical)
  • ^OR - OR operator (e.g., state=1^ORstate=2 for new OR in progress)
  • ^NQ - New query (starts a new OR condition)

Examples​

// Get new critical incidents
state=1^priority=1

// Get unassigned incidents
assigned_toISEMPTY

// Get active users in IT department
active=true^department=IT

// Get incidents with "password" in description
short_descriptionLIKEpassword

// Get high or critical priority problems
priority=1^ORpriority=2

// Get operational servers
operational_status=1^sys_class_name=cmdb_ci_server
tip

You can build complex queries in ServiceNow's UI and copy the encoded query from the URL or filter breadcrumbs. Navigate to a list view, apply filters, and copy the sysparm_query parameter from the URL.

Common Use Cases​

Incident Management​

// List all open critical incidents
List Incidents with sysparm_query: "state!=6^state!=7^priority=1"

// Get incident details
Get Incident with sys_id: "abc123..."

// Create a new incident
Create Incident with short_description: "Email server down", urgency: "1", impact: "1"

// Update incident to resolved
Update Incident with sys_id: "abc123...", state: "6", close_notes: "Server restarted"

Problem Management​

// List problems under root cause analysis
List Problems with sysparm_query: "state=3"

// Create problem from recurring incidents
Create Problem with short_description: "Database connection timeouts"

// Document root cause
Update Problem with sys_id: "def456...", workaround: "Restart service", fix_notes: "Increase connection pool"

Change Management​

// List pending high-risk changes
List Change Requests with sysparm_query: "state=-1^risk=1"

// Create change request
Create Change Request with short_description: "Upgrade database", implementation_plan: "...", backout_plan: "..."

// Update change to scheduled
Update Change Request with sys_id: "ghi789...", state: "-2", start_date: "2026-03-01 02:00:00"

CMDB Discovery​

// List all operational servers
List Configuration Items with sysparm_query: "operational_status=1^sys_class_name=cmdb_ci_server"

// Get server details
Get Configuration Item with sys_id: "jkl012..."

// Update CI operational status
Update Configuration Item with sys_id: "jkl012...", operational_status: "3" // Repair in Progress

Knowledge Base​

// Search published articles about VPN
Search Knowledge Articles with sysparm_query: "workflow_state=published^short_descriptionLIKEVPN"

// Get full article content
Get Knowledge Article with sys_id: "mno345..."

// Create new KB article
Create Knowledge Article with short_description: "How to reset password", text: "Step-by-step instructions..."

Troubleshooting​

Invalid Instance URL​

Authentication fails or API requests return 404 errors.

Cause: The ServiceNow instance URL is incorrect or malformed.

Solution:

  1. Verify your instance URL is in the format: https://[instance].service-now.com
  2. Do not include paths like /api or /nav/ui/home
  3. Ensure you're using https:// (not http://)
  4. Check that your instance is active and accessible in a browser
  5. For personal developer instances (PDIs), ensure they haven't expired (PDIs hibernate after 10 days of inactivity)

Authentication Failures​

Getting 401 Unauthorized or authentication errors.

Cause: Invalid credentials or OAuth configuration issues.

Solution:

For OAuth:

  1. Verify Client ID and Client Secret are correct in both ServiceNow and Webrix
  2. Ensure the redirect URL in ServiceNow exactly matches the one from Webrix
  3. Check that the OAuth application is Active in ServiceNow
  4. Verify access token hasn't expired (if so, try reconnecting to refresh)
  5. Check that the OAuth endpoint is set to "external clients" not "internal integrations"

For Basic Auth:

  1. Verify username and password are correct
  2. Ensure the user account is Active in ServiceNow
  3. Check that the user is not locked out due to failed login attempts
  4. Verify the user has the web_service_admin or rest_api_explorer role

Insufficient Permissions​

API requests fail with 403 Forbidden or "ACL" errors.

Cause: The authenticated user lacks required roles or access controls (ACLs) prevent the operation.

Solution:

  1. Check user roles in ServiceNow: User Administration → Users → Select user → Roles tab
  2. Common required roles:
    • rest_api_explorer - Basic API access
    • itil - Access to ITSM tables (incident, problem, change_request)
    • sn_incident_read, sn_incident_write - Incident table access
    • sn_problem_read, sn_problem_write - Problem table access
    • sn_change_read, sn_change_write - Change table access
    • cmdb_read, cmdb_write - CMDB access
    • knowledge - Knowledge base access
  3. For testing, you can temporarily grant admin role (not recommended for production)
  4. Review ServiceNow ACL rules for the specific table/operation if issues persist

Rate Limiting​

Requests fail with 429 Too Many Requests or throttling errors.

Cause: ServiceNow enforces rate limits to protect platform performance.

Solution:

  1. ServiceNow instance rate limits vary by:
    • Instance type (production, sub-production, PDI)
    • License tier
    • Specific API endpoint
  2. Default limits are typically:
    • 100 requests per 60 seconds per user/session
    • Burst capacity with gradual recovery
  3. Implement retry logic with exponential backoff in your workflows
  4. Use pagination and field filtering (sysparm_fields) to reduce request count
  5. Batch operations when possible instead of individual requests
  6. Contact ServiceNow support to increase limits if legitimate business need exists

Query Syntax Errors​

Queries return no results or unexpected results.

Cause: Incorrect encoded query syntax or field names.

Solution:

  1. Verify field names exist on the table (use ServiceNow dictionary or table schema)
  2. Check operators are correct (e.g., LIKE, ISEMPTY, !=)
  3. Use ^ for AND, ^OR for OR
  4. Field values are case-sensitive in some cases
  5. Build queries in ServiceNow UI first, then copy the sysparm_query from the URL
  6. Test queries directly in ServiceNow before using in tools
  7. Use sysparm_display_value=true query parameter to get display values instead of sys_ids

sys_id Not Found​

Get/Update operations fail with "Record not found" errors.

Cause: The provided sys_id doesn't exist or user lacks read access.

Solution:

  1. Verify the sys_id is correct (32-character hexadecimal GUID)
  2. Check that the record exists in ServiceNow by searching for it
  3. Ensure you're using the correct table (e.g., don't use incident sys_id with problem table)
  4. Verify the user has read access to that specific record
  5. Check if the record might have been deleted
  6. For related fields (like assigned_to, caller_id), these expect sys_ids not names - use List Users to get sys_ids

CORS Errors​

Browser-based applications getting CORS (Cross-Origin Resource Sharing) errors.

Cause: ServiceNow's security policies block cross-origin requests.

Solution:

  1. CORS errors only occur in browser-based applications, not server-side integrations
  2. For server-side integrations (like Webrix), CORS is not an issue
  3. For browser applications, configure CORS in ServiceNow:
    • Navigate to System Web Services → REST → CORS Rules
    • Create a new CORS rule for your domain
    • Specify allowed origins, methods, and headers
  4. Alternatively, proxy requests through your backend server

OAuth Token Refresh Failures​

Users are repeatedly prompted to reconnect or get "invalid_token" errors.

Cause: Refresh token expired, revoked, or refresh flow misconfigured.

Solution:

  1. Check the refresh token lifespan in your ServiceNow OAuth application
  2. Ensure refresh token is being stored and used correctly
  3. Verify the token endpoint URL is correct
  4. Check ServiceNow OAuth application is still active
  5. Disconnect and reconnect the integration in Webrix
  6. Review ServiceNow OAuth logs: System OAuth → OAuth Debug → OAuth Tokens
  7. If persistent, recreate the OAuth application in ServiceNow

Performance Issues​

API requests are slow or timing out.

Cause: Large result sets, complex queries, or ServiceNow instance performance.

Solution:

  1. Use sysparm_fields to return only needed fields (reduces response size)
  2. Implement pagination with sysparm_limit and sysparm_offset
  3. Filter results with sysparm_query to reduce record count
  4. Avoid querying large tables without filters
  5. Check ServiceNow instance health and performance
  6. For large data exports, use ServiceNow's batch/scheduled jobs instead of API
  7. Consider using ServiceNow's Aggregate API for counts/statistics instead of retrieving all records

Best Practices​

Security​

  • Use OAuth for production integrations
  • Create dedicated service accounts for API access
  • Grant minimum required roles (principle of least privilege)
  • Rotate credentials regularly
  • Never hard-code credentials in applications
  • Use environment variables or secure credential stores

Performance​

  • Always use pagination for list operations
  • Limit returned fields with sysparm_fields
  • Filter at the API level with sysparm_query rather than client-side
  • Cache frequently accessed reference data (users, groups)
  • Batch operations when possible

Data Quality​

  • Validate sys_ids before use
  • Provide meaningful descriptions in tickets
  • Include implementation and backout plans for changes
  • Document root cause analysis in problems
  • Link related records (incidents to problems, changes to CIs)

Maintenance​

  • Monitor API usage and rate limits
  • Review OAuth token lifespans and adjust as needed
  • Keep knowledge base up to date
  • Regularly audit user roles and permissions
  • Test integrations after ServiceNow upgrades