Skip to content

ServiceNow Setup Guide

This guide walks through enabling the ServiceNow connector so users can create IT incident tickets, check ticket status, search the knowledge base, and (for agents with the itil role) triage and update incidents from inside CampusCore.

The connector talks to ServiceNow's Table API and Knowledge Management API over per-user OAuth 2.0. Each CampusCore user authorizes with their own ServiceNow account, and ServiceNow's native ACLs enforce read/write scoping — CampusCore does not perform any custom authorization.

Prerequisites

  • A ServiceNow instance you administer (a free Personal Developer Instance from developer.servicenow.com works for piloting).
  • The admin role (or equivalent delegated authority) on that instance — required to register OAuth applications.
  • Access to the CampusCore Django admin and the workspace connectors settings UI (/settings/workspace-connectors/).
  • The public callback URL of your CampusCore deployment, e.g. https://campuscore.example.org/api/connectors/servicenow/callback.

Step 1: Register the OAuth Application Registry entry in ServiceNow

  1. Log in to your ServiceNow instance as an admin.
  2. In the filter navigator, type System OAuth and select Application Registry.
  3. Click New, then choose Create an OAuth API endpoint for external clients.
  4. Fill in the form:
  5. Name: CampusCore (or a name of your choosing — purely cosmetic).
  6. Client ID: leave the auto-generated value.
  7. Client Secret: leave the auto-generated value (you will copy it in Step 2).
  8. Redirect URL: paste the CampusCore callback, e.g. https://campuscore.example.org/api/connectors/servicenow/callback. This must match exactly what you will enter in CampusCore — trailing slashes and scheme matter.
  9. Logo URL / Comments: optional.
  10. Active: leave checked.
  11. Access Token Lifespan / Refresh Token Lifespan: keep the defaults (30 minutes / 100 days). The CampusCore connector handles refresh automatically via the authlib-based OAuth session builder.
  12. Click Submit.
  13. Reopen the row you just created. Copy the Client ID and Client Secret — you will paste both into CampusCore in the next step. The secret is only fully visible on this page; store it somewhere safe if you need a backup.

Step 2: Configure the connector in CampusCore

  1. Sign in to CampusCore as a workspace admin.
  2. Navigate to Settings → Workspace Connectors.
  3. Find the ServiceNow card and click Configure.
  4. Fill in the fields:
  5. ServiceNow Instance URL (BASE_URL): the full base URL of your instance, e.g. https://devXXXXX.service-now.com. No trailing slash required — the connector strips it if present.
  6. Client ID: paste from Step 1.
  7. Client Secret: paste from Step 1. This field is encrypted at rest via Fernet as soon as you save.
  8. Redirect URI: the same URL you entered in the ServiceNow Application Registry record.
  9. Scopes: leave as the default useraccount unless you have a specific reason to narrow it. useraccount is the scope every instance grants out of the box and covers the actions this connector uses.
  10. Click Save.
  11. Toggle Enable on the ServiceNow card. CampusCore will validate that all required config keys are populated before flipping the toggle. If any required field is missing, the toggle is blocked and the form stays open with the missing field highlighted.

The ServiceNow connector is now available to users. No other admin action is required — individual users will complete the per-user OAuth flow themselves.

Step 3: Users connect their own ServiceNow accounts

Each user connects once from their own CampusCore session:

  1. The user opens Settings → Connectors and clicks Connect on the ServiceNow card.
  2. They are redirected to the ServiceNow consent screen. They sign in with their own ServiceNow account and click Allow.
  3. ServiceNow redirects them back to CampusCore. The connection row is created with status=active, and the per-user access/refresh token is stored encrypted on Connection.credentials.
  4. The user can now ask the agent questions like "What IT tickets do I have open?" or "How do I reset my password?".

Because each user authorizes with their own ServiceNow identity, the native ACL layer enforces that users can only see data they are entitled to see in ServiceNow itself. A regular user sees only their own tickets; an itil user sees their assigned group's queue; no CampusCore-side filtering is needed.

Step 4: Verify the connection

As a user with an active connection, ask the agent:

"What IT tickets do I have open?"

The agent should call servicenow__get_my_open_incidents, and the trace UI should show a Table API request with: - URL ending in /api/now/table/incident - sysparm_query=caller_id=javascript:gs.getUserID()^active=true^ORDERBYDESCopened_at - sysparm_display_value=true and sysparm_exclude_reference_link=true on the query string

Then try:

"Open a ticket saying my laptop keeps bluescreening"

The agent should call servicenow__create_incident. Because this is a write action, the agent surfaces a confirmation event and waits for you to approve before the POST fires. Approve, then verify the incident appears in the ServiceNow UI under your caller record.

If your instance has the Knowledge Management API enabled, test:

"How do I reset my password?"

The agent should call servicenow__search_knowledge_base and return a list of article summaries with clickable URLs that deep-link back into the instance.

Available actions

The connector exposes 10 actions across two personas:

Requesters (any authenticated user): - create_incident — Create a new IT incident ticket. Gated with permission="user_confirm". - get_my_open_incidents — List the caller's currently open incidents. - get_incident — Get full details for a specific incident by its number (e.g. INC0012345). - search_knowledge_base — Search the knowledge base for articles. - get_my_service_requests — List the caller's service requests (catalog items).

IT service-desk agents (require the itil role in ServiceNow): - search_incidents — Search incidents by text, state, priority, assignment group, or assignee. - get_incident_work_notes — Get the chronological work-note history for an incident. - add_incident_work_note — Append a work note. Gated with permission="user_confirm". - update_incident_state — Transition an incident to a new state. Gated with permission="user_confirm". - reassign_incident — Reassign to a new assignment group or assignee. Gated with permission="user_confirm".

A non-agent user can attempt agent actions but ServiceNow will simply return no data — CampusCore does not filter the action list per-role, it relies on upstream ACLs.

Troubleshooting

"Failed to obtain access token" when users click Connect. Check that the Redirect URL on the ServiceNow Application Registry record exactly matches the REDIRECT_URI entered in CampusCore. Scheme, host, path, and trailing slash must all match byte-for-byte.

Users see "Invalid or expired state parameter". This usually means the connect flow took longer than 10 minutes (the cache TTL on the OAuth state token). Ask the user to click Connect again and complete the flow promptly.

The agent says it can't find a ticket by number. Double-check the user's ServiceNow ACLs. get_incident resolves by number via the Table API, so ServiceNow has to grant the user read access to that row. A user without the itil role only sees incidents where they are the caller.

Knowledge search returns no results. Not every ServiceNow instance has the Knowledge Management API (/api/sn_km_api/knowledge/articles) enabled. The connector currently ships only the KM API path. If your instance is missing it, open a support issue and we'll add a Table API fallback that queries kb_knowledge directly.

Rotating credentials

To rotate the OAuth client secret:

  1. In ServiceNow, open the Application Registry record and click Reset Client Secret. Copy the new secret.
  2. In CampusCore Settings → Workspace Connectors → ServiceNow → Configure, paste the new secret and save.
  3. Existing user connections continue working — only the workspace-level client secret changes. If you want to force all users to re-authorize, disable and re-enable the connector or revoke tokens on the ServiceNow side.