Add a Simplesat survey to a ServiceNow email notification, and the people who contact your service desk can rate the help they got right from that email. The survey code works on its own, so you don't need to connect ServiceNow to send surveys.
Connecting ServiceNow lets you put each rating on the incident or case it rates, and bring incident and case details, the customer and the agent into Simplesat.
What the ServiceNow integrations do
The ServiceNow page in Simplesat lists its integrations under Ticket integrations. You switch each one on separately with Activate integration.
Integration | What it does | Where it shows |
Pull incident details | Adds the incident's details, its caller and the user who opened it to the response | The response, in Simplesat |
Pull case details | Adds the case's customer, company and the user who resolved it to the response | The response, in Simplesat |
Sync feedback to incident custom fields | Writes the rating, sentiment and comment to fields on the incident | The incident |
Sync feedback to case custom fields | Writes the rating, sentiment, comment and metric to fields on the case | The case |
Sync feedback to incident labels | Adds a rating label and a sentiment label to the incident | The incident |
The integrations run only on surveys connected to ServiceNow. A survey is connected when:
its delivery method is External email embed with the ServiceNow option, or
it's an Event-based or Web-embed survey with Connected service set to ServiceNow.
None of them lets you choose which surveys it runs on, so once one is on, it runs on every response from a survey connected to ServiceNow. Turn on the incident integrations if your surveys go out from incident notifications, and the case integrations if they go out from case notifications.
Note: If we've changed one of your ServiceNow integrations for you, it can work differently from what's described here. Contact us to check what yours does.
Before you start
The ServiceNow integrations come with every Simplesat plan. To connect ServiceNow and switch integrations on, you need the Manage integrations permission in Simplesat. Owner and Admin have it by default.
You connect with the username and password of a ServiceNow user, and the integrations then act as that user. Pick a user who will keep their ServiceNow access and whose password you control, such as a dedicated integration user, rather than a teammate's own account.
If your team signs in to ServiceNow only through SSO, create a dedicated integration user with a password and select Web service access only on that user. ServiceNow then lets Simplesat connect with that password, even if your instance restricts password sign-in. The user can't sign in to ServiceNow's own screens, but it doesn't need to.
That user needs to be able to:
read and update the incidents or cases your surveys go out from
read users and companies, for the pull integrations
create labels, for Sync feedback to incident labels (its section below shows how)
If your security team asks what a connected tool can read and write, point them to Integration security, permissions and data flow.
Connect ServiceNow
Have these details ready:
Field | What to enter | Example |
ServiceNow URL | Your full ServiceNow address, starting with |
|
Username | The ServiceNow user's username |
|
Password | That user's ServiceNow password |
On the Integrations page, open ServiceNow.
Click Authenticate.
Fill in the fields with the details above.
Click Authenticate.
When the page shows Authenticated with ServiceNow, you can switch integrations on with Activate integration. The custom field and label integrations need setup in ServiceNow first, described under Feedback in ServiceNow.
Before you rely on an integration, run a real incident or case through it, following Testing an integration end to end.
Send surveys in ServiceNow notifications
ServiceNow decides when the survey goes out: it's part of the notification you add it to, such as the one sent when an incident is resolved.
Create or open the survey and choose External email embed.
Under Choose where to add your survey, choose ServiceNow.
On Publish, click Generate embed code.
Choose HTML and click Copy survey.
In ServiceNow, go to All → System Notification → Email → Notifications and open the notification that should carry the survey. For resolved incidents, that's Incident resolved.
On the What it will contain tab, switch Message HTML to source code and paste the HTML where you want the survey to appear.
Click Save, then Update.
To test it, create an incident with yourself as the caller, resolve it, and click a rating in the email.
When ServiceNow sends the notification, it fills in the placeholders in the survey code, so each response arrives with its incident, customer and agent. The ticket ID is the record's sys_id, and it's how the integrations find the incident or case.
What the code carries | ServiceNow placeholder |
Ticket ID (the record's sys_id) |
|
Ticket subject |
|
Customer email |
|
Customer ID |
|
Customer first and last name |
|
Company name |
|
Team member email |
|
Team member ID |
|
Team member first and last name |
|
Incident number, saved as the ticket field |
|
Category, severity and priority, saved as the ticket fields |
|
A case has no caller, so in a case notification the customer and company placeholders above come out empty. Edit every rating link in the code you paste there: replace ${caller_id.company.name} with ${account.name}, and caller_id with contact in the four customer placeholders. Leave everything else as it is, including the parameter names in the links.
What the code carries | Case placeholder |
Customer email |
|
Customer ID |
|
Customer first and last name |
|
Company name |
|
In a consumer case, use ${consumer.email}, ${consumer.first_name} and ${consumer.last_name} for the customer's email and name instead.
For placeholders in general, see Placeholders and merge fields, and to weigh this against Simplesat's other ways of sending surveys, see Choosing a survey delivery method.
Feedback in ServiceNow
Simplesat waits at least five minutes after a response arrives before it writes to ServiceNow, and writes again whenever the response changes (more on the timing in Writing feedback back, and mapping the fields).
Sync feedback to incident custom fields
This integration writes the rating, the sentiment and the comment to three fields on the rated incident. Their column names have to be exactly u_simplesat_rating, u_simplesat_sentiment and u_simplesat_comment. ServiceNow builds a new field's column name from its label, so label the fields Simplesat rating, Simplesat sentiment and Simplesat comment and the names come out right.
You'll add these three fields:
Name | Type | Field length |
Simplesat rating | Integer | |
Simplesat sentiment | String | Small (40) |
Simplesat comment | String | Large (1000) |
In ServiceNow, open any incident, right-click the bar at the top of the form, and choose Configure → Form Layout.
Under Create new field, add the fields above.
Click Save. To move the fields on the form, use Configure → Form Design.
In Simplesat, click Activate integration on Sync feedback to incident custom fields.
Sync feedback to case custom fields
This integration writes the rating, the sentiment, the comment and the metric to fields on the rated case. Create the fields on the case form the same way as for incidents: the same three, plus Simplesat metric as a String field. Their column names are then u_simplesat_rating, u_simplesat_sentiment, u_simplesat_comment and u_simplesat_metric. The metric field gets CSAT, NPS, CES or 5-STAR.
Then, in Simplesat, click Activate integration on Sync feedback to case custom fields.
Sync feedback to incident labels
This integration adds these labels to the rated incident:
A rating label:
simplesat_followed by the metric and the rating, such assimplesat_CSAT_4,simplesat_NPS_9orsimplesat_5-STAR_5.A sentiment label:
simplesat_sentiment_positive(green),simplesat_sentiment_neutral(yellow) orsimplesat_sentiment_negative(red).
The first time it runs, it creates the whole set of Simplesat labels in ServiceNow. It never removes a label, so if a rating changes, the incident ends up with a second rating label.
Heads up: Currently, a CES rating of 5 doesn't get a rating label. It still gets its sentiment label.
Before you activate it, let the connected user add labels to incidents. You need the security_admin role in ServiceNow to do this.
In ServiceNow, go to All → System Security → Access Control (ACL).
Search for
label_entry.table_keyand open its write rule.Click your profile picture, choose Elevate role, select
security_adminand click Update.Under Roles, insert a new row with a role the connected user has. Leave the other roles in place.
Click Update.
In Simplesat, click Activate integration on Sync feedback to incident labels.
Incident and case details in Simplesat
The pull integrations read the incident or case itself and fill in the response's ticket, customer and agent from it, on the same timing as the feedback integrations. What they bring in replaces the ticket fields and team members the response arrived with. For how Simplesat links feedback to tickets, customers and agents in general, see Attribution: linking feedback to tickets, customers and agents.
Pull incident details
This integration reads the incident and adds to the response:
the incident's short description as the ticket subject
its number, impact, urgency, type, priority, severity and category, as ticket fields (category is saved as
ticketGroup)the caller as the customer, with their name, email and ServiceNow ID, and their company
the user in the incident's Opened by field as the team member, with the role Opened by
Heads up: Responses then credit whoever opened the incident, not the assigned agent from ${assigned_to…} in the survey code.
Pull case details
This integration reads the case and adds to the response:
the ticket subject, from the case
the customer, found among your ServiceNow users by the response's customer email, with their name, email and ServiceNow ID, and their company
the user in the case's Resolved by field as the team member, with the role Resolved by
If no ServiceNow user has the response's customer email, or more than one does, no customer is added.
Change the ServiceNow user or instance
Reconnect to switch to a different ServiceNow user or to move to another instance. Reconnect too when the connected user's password changes or they lose access: the integrations stop, but the page still shows Authenticated with ServiceNow.
Click Revoke access.
Click Authenticate and enter the new details.
Check that each integration you use shows Deactivate integration, which means it's on. Connecting again switches back on every integration that was on before, with its settings. If one is still off, click Activate integration on it.
Heads up: Responses that arrive while access is revoked aren't written to ServiceNow, so do the steps in one go.
Survey code in your ServiceNow notifications keeps working throughout.
Troubleshooting
I get a 400 error when I connect ServiceNow
Check that ServiceNow URL holds your full ServiceNow address, starting with https://, such as https://acme.service-now.com or https://acme.servicenowservices.com. The address should end at the domain, with no slash after it. Then check the username and password: they have to belong to a ServiceNow user that has a password, which users who sign in only through SSO don't. If you still see the error, contact us.
My responses credit the wrong person as the team member
Pull incident details credits the user in the incident's Opened by field, and replaces the agent the survey code carried. So if an incident was opened by the caller, a guest user or an integration user, that's who the response credits. Without Pull incident details, responses keep the agent from ${assigned_to…} in the survey code.
I see ACL Exception Update Failed on my case fields
ServiceNow refused the update: the connected user isn't allowed to update cases, or the Simplesat fields on them. Give that user those rights in ServiceNow, or reconnect as a user who has them.
Feedback doesn't show up on my ServiceNow incidents or cases
Check each of these:
The survey is connected to ServiceNow: External email embed with the ServiceNow option, or Connected service set to ServiceNow.
The response's ticket ID is the record's sys_id, from
${sys_id}in the survey code.For the custom field integrations, the fields' column names are exactly the
u_simplesat_names listed above.For labels, the connected user can add labels to incidents through the
label_entry.table_keywrite rule.At least five minutes have passed since the response arrived.
The integration is on: its button shows Deactivate integration.
If none of this explains it, send us the response's link.
My CES ratings of 5 don't get a label in ServiceNow
Currently, Sync feedback to incident labels doesn't add a rating label for a CES rating of 5. The incident still gets its sentiment label.
My survey email doesn't go out from ServiceNow
ServiceNow sends the notification, so outbound email has to work in ServiceNow. All → System Diagnostics → Email Diagnostics shows whether it does. To turn sending on, go to All → System Mailboxes → Administration → Email Properties, and set up an email account under Email Accounts.
My ServiceNow integrations stopped working, but the page still says Authenticated
Simplesat doesn't check the connection after you connect. If the user's password changed or the user lost access, the integrations fail and the page still reads Authenticated with ServiceNow. Click Revoke access, then Authenticate with the current password. The integrations that were on switch back on by themselves. Check that each one you use shows Deactivate integration, and click Activate integration on any that's still off. For anything else the page shows, check Integration error messages and what they mean.
FAQ
Can I connect ServiceNow if we sign in with SSO?
Yes. The connection signs in with a ServiceNow username and password, so create a dedicated integration user with a password and select Web service access only on that user. ServiceNow then lets Simplesat connect with that password, even if your instance restricts password sign-in.
Why is the ticket ID on my responses a long code instead of the incident number?
It's the record's sys_id, which the integrations use to find the incident or case. The incident number is on the response too, as the ticket field number.
How do I make the ticket link on a response open the incident or case?
Set the survey's Ticket URL on its Configure tab, with {{ ticket_id }} where the sys_id goes and your instance in place of acme. For a case, for example: https://acme.service-now.com/now/cwf/agent/record/sn_customerservice_case/{{ ticket_id }}. For an incident, put incident in place of sn_customerservice_case.
Do I need to connect ServiceNow to send surveys?
No. Survey code in a ServiceNow notification works without connecting. Connect to put feedback on your incidents and cases and to pull their details into Simplesat.
Does the ServiceNow integration cost extra?
No. The ServiceNow integrations come with every Simplesat plan.