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. Open the All menu, search for Application Registry, and open it (it lives under System OAuth).
  3. Click New. ServiceNow asks what kind of OAuth application to set up; 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 value ServiceNow fills in; you will copy it in Step 2.
  7. Client Secret: leave it blank to have ServiceNow generate one on submit, or type your own. Either way you 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. Refresh Token Lifespan / Access Token Lifespan: keep the defaults (100 days / 30 minutes). The CampusCore connector handles refresh automatically via the authlib-based OAuth session builder.
  12. Click Submit.
  13. Reopen the record you just created. Copy the Client ID. The Client Secret is masked behind a lock icon - click the lock to reveal it, then copy it. You will paste both into CampusCore in the next step, and the secret is only readable here, so 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.

Then test knowledge search:

"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. It can then call servicenow__get_knowledge_article to read one article in full and answer from it.

Available actions

The connector exposes these actions, grouped by who they serve.

Every connection: - get_user_info - Read the connected ServiceNow account's name, email and user name. The Test button in Settings > Connectors calls it.

Requesters (any authenticated user): - create_incident - Create a new IT incident ticket with the connected user as its caller. 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_knowledge_article - Read one knowledge article in full by its number (e.g. KB0010001), as plain text cut at 12,000 characters. - 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. Resolving or closing needs both close notes and a resolution code, which the instance's data policy requires. 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

Users see "Could not connect to ServiceNow. ServiceNow did not issue a token. Ask an administrator to check the connector's Redirect URI." 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. CampusCore asks for the token once and does not retry, because ServiceNow accepts an authorization code only once; the person can press Connect again after the fix.

Users see "This sign-in could not be matched to your session". There are two usual causes. The sign-in took longer than 10 minutes, which is how long CampusCore keeps it open; ask the person to press Connect again and finish promptly. Or the REDIRECT_URI host is not the host people open CampusCore on, for example campuscore.example.edu against www.campuscore.example.edu. The sign-in is tied to the person's session, and the browser does not send that session's cookie to a different host, so every return fails the same way. Set REDIRECT_URI, and the Redirect URL on the Application Registry record, to the host people actually use.

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. The connector searches through the Knowledge API (/api/sn_km_api/knowledge/articles), which comes from the Knowledge Management REST API store app. When the instance does not have that app, ServiceNow answers with a 400, and the connector searches the kb_knowledge table's text index instead, limited to published articles. Either way ServiceNow applies the user's own access, so an article the user cannot read in ServiceNow never appears. Installing the store app gives better ranking and highlighted snippets.

An approved action fails with "ServiceNow refused the request (403)". ServiceNow answers 403 when an access rule or a data policy refuses the change, and the message carries ServiceNow's own reason, for example "The following fields are mandatory: Resolution code". The connection stays connected, because reconnecting would not change the outcome. Fix the cause the message names, such as the user's roles or the field the data policy requires. A 401, by contrast, means the token itself was rejected, and the connection is marked expired until the user reconnects.

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.