Solution-Deployment

ServiceNow Environment Configuration

Prerequisites

This guide assumes the following configuration has already been completed

. ccx-servicenow cloudformation has been deployed in your aws account

. You are using the Next Experience UI ServiceNow UI

Install Openframe Plugin

1. Log into your ServiceNow instance as Administrator

2. From the All menu search for 'Plugins'

3. In the plugins search bar, search for openframe

4. Open the Openframe plugin page and select install

Configure Openframe Plugin

1. From the All menu search for 'openframe' - select Configurations

2. Select New

3. On the Openframe configuration page:
-Provide a Name - this is what the softphone name will display as.
-Ensure 'Active' is ticked
-Provide Width and Height - the defaults are 400 Wide and 522 High
-Select the User Groups who should have access to the softphone
-Set the URL to the amplify url that was provided to you in an email after you installed the cloudformations.

Whitelist Softphone

1. From the All menu enter sys_properties.list into the search bar and hit enter

2. In the System Properties search for glide.ui.concourse.onmessage_enforce_same_origin_whitelist

3. In the value field enter the amplify url provided in your setup email, and your Amazon Connect instance url

Create API User

Create a user in ServiceNow that has access to the tables you want to be able to look up and enable screenpops.

Note the Username and Password as this will be required in the AWS Console Config setup

Enable Click to Call

1. From the All menu search for decorators and select Field Decorators

2. Create a new decorator

3. Provide the following field values to the new Decorator and save.

AWS Console Config

Update Parameter Store Values

1. From AWS Console go to 'Parameter Store'

2. There will be a parameter named /ccx-<your servicenow domain>/servicenow.cti/default/service_account_user

3. Edit this parameter and update Value field with the username of the API user you created in ServiceNow earlier. Save changes

4. There will be another parameter named /ccx-<your servicenow domain>/servicenow.cti/default/service_account_password

5. Edit this parameter and update Value field with the password of the API user you created in ServiceNow earlier. Save changes

Lambda Variables

1. From AWS Console go to 'Lambda' and search for ccx-snContactLensSummary

2. On this lambda go to the Configuration tab

3. Update the snAttribute value to match the user-defined attribute defined in the contact flow which contains the ServiceNow interaction id.

Amazon Connect Configuration

The Amazon Connect flow calls the snInvokeAPI Lambda using an AWS Lambda function block. Every call must pass an sn_operation parameter, which selects the action to run. All other parameters are passed in the same block as Function input parameters (Connect sends them all as strings).

Each operation returns a flat set of keys. Read them in later blocks with $.External.<key>, or store them with a Set contact attributes block (Use attribute > External).

If sn_operation is missing or unsupported, the Lambda returns statusCode = 400 along with a list of supported operations. If ServiceNow rejects a request, or the Lambda fails, the invocation errors, so use the block's Error branch to handle it.

Supported operations

sn_operation	Purpose
genericLookup	Query any ServiceNow table by field and value
lookupUserByMobile	Find an active sys_user by mobile number
lookupCustomerByPhone	Find contacts (customer_contact) and accounts (core_company) by phone number
createInteraction	Create an interaction record for the call
createIncident	Create an incident record

Table names default to sys_user, customer_contact, core_company, incident and interaction. They can be overridden with the SSM parameters/environment variables sn_user_table, sn_contact_table, sn_account_table, sn_incident_table and sn_interaction_table.

Lookup operations

genericLookup

Parameter	Required	Description
table	Yes	ServiceNow table to query (e.g. sys_user, incident, core_company)
queryField	Yes	Field to search against (e.g. phone, email, name)
queryValue	Yes	Value to search for. Cannot be null or empty
operator	No	ServiceNow query operator (e.g. =, LIKE, STARTSWITH). Defaults to LIKE. Ignored for phone/mobile fields, which always use CONTAINS
limit	No	Max records to return (integer). Defaults to sn_lookup_limit, otherwise 5
returnFields	No	Comma-separated fields to return. Defaults to sn_sysparm_fields, otherwise sys_id,name. Each field is returned as a top-level key (see below)
normalizePhone	No	Set to false to disable phone normalization. When enabled and queryField contains "phone" or "mobile", the value is reduced to digits, the NZ country code (64) is removed, and the leading 0 is removed

Returned keys:

• sn_lookup_status - no match, match or multimatch
• sys_id - comma-separated sys_ids of the matches
• sn_record_names - comma-separated display names
• sn_record_urls - comma-separated ServiceNow record URLs
• one key per field in returnFields (comma-separated values; sys_id is always included)
• status - FOUND or NOT_FOUND
• message - readable summary of the result

lookupUserByMobile

Parameter	Required	Description
mobileNumber	Yes	Caller's mobile number. mobile, mobile_phone and MobileNumber are also accepted

Searches active users on mobile_phone (normalized, CONTAINS). Returned keys: sn_lookup_status, sn_sys_id, sn_user_name, sn_user_url, status, message.

lookupCustomerByPhone

Parameter	Required	Description
phoneNumber	Yes	Caller's phone number. phone, phonenumber and PhoneNumber are also accepted

Searches contacts on phone / mobile_phone and accounts on phone / phone_number (normalized, CONTAINS). Matches from both tables are merged. Returned keys: sn_lookup_status, sn_record_ids, sn_record_names, sn_record_urls, status, message.

Create operations

For both create operations, the Lambda does not rename, default or validate any parameters. Every parameter except sn_operation is posted to ServiceNow exactly as supplied, with empty values dropped. This means:

• Parameter names must be the exact ServiceNow column names for the table (e.g. short_description, assignment_group).
• Any column on the table can be set without changing the Lambda.
• Names that are not columns on the table are ignored by ServiceNow.
• Omitted fields use the table's own ServiceNow defaults.
• If ServiceNow rejects the payload (e.g. a mandatory field is missing), its error is returned and the Lambda invocation fails.

createInteraction

Parameter	Required	Description
type	Yes	Type of contact, e.g. phone or chat

Common optional parameters: opened_for (sys_user the interaction is for), short_description, state (new, on_hold, work_in_progress, wrap_up, closed_complete, closed_abandoned), subject, plus any other interaction column such as assignment_group, channel or opened_by.

createIncident

No parameters are enforced by the Lambda; send whatever your ServiceNow incident table requires. Common parameters: caller_id, short_description, description, urgency, impact, category, subcategory, contact_type, assignment_group, assigned_to.

Returned keys (both operations), where <record> is interaction or incident:

• status - SUCCESS
• message - e.g. Incident INC0010001 created successfully
• <record>.sys_id, <record>.number, <record>.short_description, <record>.state, <record>.contact_type
• <record>.url / <record>.instanceUrl - link to the record in ServiceNow
• <record>.full_record - the full record returned by ServiceNow
• timestamp

Example flow

Step	Block	Parameters	Comments
1	AWS Lambda function	sn_operation = genericLookup table = sys_user queryField = mobile_phone queryValue = $.CustomerEndpoint.Address returnFields = sys_id,name,email	Look up the caller. Check $.External.sn_lookup_status to branch on no match / match / multimatch
2	Set contact attributes	Store sys_id, sn_record_names, sn_record_urls etc. from $.External	Keep the lookup results for later blocks and screenpops
3	AWS Lambda function	sn_operation = createInteraction type = phone opened_for = $.Attributes.sys_id short_description = (optional) state = (optional)	Log the call as an interaction
4	Set contact attributes	Store $.External.interaction.sys_id, $.External.interaction.number and $.External.interaction.url	Used by the softphone to attach the interaction and by snContactLensSummary for call summaries
5	AWS Lambda function	sn_operation = createIncident caller_id = $.Attributes.sys_id short_description = (as required)	Optional - only when an incident should be raised
6	Set contact attributes	Store $.External.incident.number and $.External.incident.url	Optional - use for screenpops or agent whisper