After your first successful test, walk through this checklist before declaring go-live. Each item is a behaviour that is hard to debug after agents are on the line.

• Inbound voice — a known contact's phone triggers a screen-pop within 2 seconds of answer.
• Unknown caller — a number not in Contact/User creates the Interaction (or Incident/Case) without a contact link.
• Multiple matches — two contacts sharing a phone show the match-selection UI.
• Click-to-dial — dialling from a phone field opens an outbound call in Genesys.
• Transfer — blind/consult transfer re-pops the same record on the receiving agent.
• Wrap-up — disconnect writes wrap-up code and Genesys conversation URL to work notes.
• Copilot Summary — when copilotSummaryTargetField is set (e.g. work_notes), the Genesys Copilot summary is appended to that field after wrap-up (typically within 60 seconds).
• Participant data — the ServiceNow record sys_id appears as servicenow_<table>_id on the Genesys interaction attributes.
• Role scoping — a user without the role cannot see the phone icon at all.

Still stuck? See Support or download the configuration guide from Install Guide.

Customer Service Management, IT Service Management and Service Operations Workspace run on the same connector runtime. The widget, search, screen-pop, transfer, click-to-dial, phone log and Copilot behaviour described on this page is identical in all three — what changes is the table searched for the caller and the record type created.

Service Operations Workspace needs no separate configuration: agents who work Incidents there get the same widget, lookup and screen-pop as ITSM agents in the classic or Agent Workspace UI.

Every inbound voice or digital interaction follows the same path through the connector. These five stages cover field mapping and troubleshooting.

Each step is independently toggleable and logged — if a record isn't being created, step 3 is where to look; if it's being created but not popping, step 4.

The connector writes the sys_id and URL of every auto-created ServiceNow record back into Genesys as participant data, using the keys:

• servicenow_<tablename>_id
• servicenow_<tablename>_link

Example: a new SN Interaction produces servicenow_interaction_id and servicenow_interaction_link.

Data flows in three directions. Note which direction an attribute uses when mapping fields — the property that controls it differs.

Incidents have richer priority semantics than Cases. Plan these before your first go-live:

• Impact / Urgency vs Priority — ServiceNow computes priority from impact and urgency. Map the two inputs rather than the output, or your business rule will recompute and override.
• SLA start on creation — an auto-created Incident starts its SLA clock the moment the connector inserts it. To start the clock only when the agent confirms, disable enableIncidentCreation and create manually.
• Queue-based routing — use queueName on the Genesys side to stamp assignment_group on the Incident. Avoids the usual "who owns this?" handoff.
• Business vs employee hours — Genesys does not know your ServiceNow business-hours schedule. If the Architect flow should route differently during off-hours, calculate that on the Genesys side and pass it as participant data.

• No Screen-pop on Outbound — Skip auto screen-pop for outbound interactions. Useful when agents manually initiate calls for existing cases they already have open.
• Embedded Interaction Window — Show a built-in interaction detail panel inside the widget, so agents can see call attributes without navigating away from the record.
• Configurable Caller ID — Let agents choose their outbound caller ID before dialling (useful for multi-brand or multi-region teams).
• Server-side Logging — Extra server-side logging from the widget for troubleshooting. Leave off in production unless actively diagnosing.
• Custom Entity Tables — Persist additional SN table IDs as Genesys participant data (beyond interaction/case/incident/HR case).
• Wrap-up Notes on Disconnect — Show the Genesys wrap-up notes on the ServiceNow record on disconnect.
• Genesys Copilot Summary (v1.4.8+) — Fetch and append the Genesys Copilot conversation summary to the linked record after wrap-up. Controlled by copilotSummaryTargetField (set to a field name to enable; leave empty to disable).
• Trace Logging (v1.4.8+) — Correlated debug logging across widget and server. Controlled by enableTraceLogging. Logs automatically redact phone numbers, email addresses, and sensitive interaction attributes.
• Call History (v1.4.6+) — Surface recent call history inside the widget.
• Theme Color (v1.4.6+) — Brand-match the widget to your ServiceNow theme.
• Custom Call Controls (v1.4.6+) — Choose which call-control buttons are visible and in what order.

Sample configurations. Copy and adapt for your properties. The gc… values are example participant-data keys you define in your Architect flow, and u_… fields are custom ServiceNow columns — substitute your own names.

Recipe 1 · Rich auto-created Case

Populates the most useful fields from Genesys participant data so agents aren't re-typing context. Add a few skill-based fields as your IVR matures.

// interaction_key property - Case fields
{
  "short_description": "gcSubject",
  "description":       "gcNotes",
  "category":          "gcIntent",
  "priority":          "gcPriority",
  "u_ivr_path":        "ivrSelections",
  "u_queue_name":      "queueName",
  "u_genesys_call_id": "conversationId"
}

Recipe 2 · Blank short description

Let agents author the short description themselves so the Case isn't pre-populated with a default string. Added in v1.4.3.

// interaction_key property - Case fields
{
  "short_description": "blank",
  "description":       "gcNotes"
}

Recipe 3 · Update status on transfer

When a call is transferred (blind or consult), update the Case state to "Work In Progress" and stamp the receiving agent.

// updateOnTransfer property
{
  "case": {
    "state":          "2",
    "assigned_to":    "gcReceivingAgentId",
    "u_last_transfer":"gcTransferTimestamp"
  }
}

Recipe 4 · Direct screen-pop from Architect

When your Architect flow already knows the Case number (for example, a self-service bot resolved to a case), bypass contact search and pop it directly.

// Genesys participant data
directscreenpop_table = "sn_customerservice_case"
directscreenpop_field = "number"
directscreenpop_value = "CS0012345"

Recipe 5 · Auto-categorise an Incident from the IVR selection

Map the two priority inputs rather than priority itself, so ServiceNow computes the result.

// interaction_key property - Incident fields
{
  "short_description":    "gcSubject",
  "description":          "gcNotes",
  "category":             "gcCategory",
  "subcategory":          "gcSubcategory",
  "impact":               "gcImpact",
  "urgency":              "gcUrgency",
  "assignment_group":     "gcAssignmentGroup"
}

Recipe 6 · Pop the Major Incident during a known outage

Let Architect decide: when a configuration item is in "Outage" state, set the direct screen-pop attributes so agents land on the existing Major Incident. Direct screen-pop opens that record instead of running the configured search, and only falls back to the default behaviour if one of the three attributes is missing.

// Genesys participant data
directscreenpop_table = "incident"
directscreenpop_field = "number"
directscreenpop_value = "INC0456789"   // the Major Incident

Recipe 7 · Stamp caller context on every outbound call

So supervisor dashboards can trace which record prompted each outbound dial. The connector adds these automatically on click-to-dial.

// Click-to-dial participant attributes (auto-added by connector)
servicenow_incident_id   = "<sys_id>"
servicenow_incident_link = "https://<instance>.service-now.com/incident.do?sys_id=<sys_id>"

The connector is designed to handle a full contact-center shift without breaking a sweat. Useful numbers to size against:

HRSD mode lets HR Service Delivery agents receive Genesys interactions and work HR Cases without exposing sensitive information until they've confirmed the right record. With enableHRCaseLookup active, the default fallback when no matching HR case exists is a ServiceNow interaction record. When enableHRCaseCreation is enabled, the connector can auto-create or manually create sn_hr_core_case records instead.

HRSD handling is the most cautious mode the connector offers. Four design choices set it apart:

1. Interaction fallback by default. When HR case lookup is active and no matching HR case exists, the connector creates a ServiceNow interaction record unless enableHRCaseCreation is enabled. With enableHRCaseCreation=true, auto and manual sn_hr_core_case creation is available.
2. Limited participant data mapping. HR Case fields are mapped through the same interaction_key property; only fields explicitly listed in the Configuration Guide's HR allow-list are writable from Genesys.
3. Work-notes are append-only. The connector never rewrites existing HR Case fields on disconnect — it appends. This preserves the audit trail.
4. Role separation. HR agents typically do not have the standard CSM / ITSM roles. The connector honours this and only exposes HRSD-specific actions.

The caller is identified against the standard ServiceNow user record, sys_user. For voice, the fields searched depend on voiceSearchField.

Recipe 1 · Minimal HR Case mapping

HR Case fields are mapped through the same interaction_key property used for every record type. Include mandatory HR Case fields such as hr_service in the mapping; the opened_for contact field is the exception and is set by the connector itself. gcSubject is an example Genesys participant-data key name, not a fixed built-in.

// interaction_key property - HR Case fields
{
  "short_description": "gcSubject",
  "hr_service":        "<sys_id>",
  "subject_person":    "<sys_id>"
}

Recipe 2 · Opt-in agent notes on wrap-up

Leave showWrapUpNotes set to No globally, so After Call Work notes are only captured where HR has agreed they are appropriate.

External Routing lets Genesys Cloud hand out ServiceNow work — cases, incidents, HR cases and live chat — to your agents, using the same queues, skills and priorities that already route calls and messages. Instead of agents picking work from a list, Genesys assigns it, and the record opens on screen the moment the agent accepts.

Because the work travels through Genesys Cloud, it sits alongside every other channel in the dashboards and reports your supervisors already use.

How it works

1. A case, incident, HR case or chat matches the rules of a ServiceNow queue you have marked for Genesys routing.
2. Genesys Cloud takes it from there, routing it by queue, skill and priority like any other interaction.
3. The work is offered to a suitable agent in the Genesys widget inside ServiceNow.
4. The agent accepts, and ServiceNow opens the record for them.

Four kinds of ServiceNow work can be handed to Genesys Cloud. Each one is picked up from a queue you have marked for Genesys routing, and lands in the workspace the agent already uses.

• One routing engine for every channel — ServiceNow work queues up in Genesys Cloud next to calls and messages, so a single set of rules decides who gets what.
• The record opens by itself — the agent who accepts the work sees the case, incident, HR case or chat straight away, with no searching.
• Context travels with the work — details from the ServiceNow record are attached to the interaction, ready for your routing rules and reports. You choose which details (v1.0.6+).
• Cancelled work stops being offered — when a queued item is cancelled in ServiceNow, the matching Genesys interaction ends automatically, and keeps retrying until it does (v1.0.6+).
• Optional record close — the case, incident, HR case or chat can be closed at the same time, so nothing is left half-finished (v1.0.6+).
• No duplicate conversations — if the same record returns to the queue, agents pick up the existing conversation rather than starting a second one.
• Availability stays in step — an agent on a break or in training in Genesys is not handed ServiceNow work, and vice versa.
• Transfers keep the record — when work moves to another agent, their workspace opens the same record.

In ServiceNow

• The Genesys Cloud Connector, installed and activated.
• The Advanced Work Assignment plugin, which provides the queues the work is routed from.
• The Agent Chat plugin, if you want to route live chat.

In Genesys Cloud

• An Open Messaging platform integration, which is how ServiceNow work reaches Genesys.
• An inbound message flow in Architect that sends the work to the right queue.
• Its own OAuth client using the Client Credentials grant, registered in ServiceNow under System OAuth > Application Registry. External Routing does not share the connector's client.

Agent access

An agent needs three roles before Genesys can hand them work. The Genesys Integration Permissions group grants them together:

• sn_openframe_user — loads the Genesys widget inside ServiceNow.
• genesys_sn_role — lets the agent use the connector.
• gen_ext_sn_role — lets the agent be assigned routed work.

What it uses in your instance

Configure on Genesys External Routing > Properties (category: External Routing Properties).

// participantData example
{
  "short_description": "short_description",
  "priority": "priority"
}

// presenceMap example
{
  "Available": "onqueue",
  "Away": "Away",
  "Offline": "Busy",
  "Meal": "Meal"
}