From Bright Pattern Documentation
< 5.8:Service-now-integration-guide
Revision as of 06:04, 13 September 2024 by Wyler.metge (talk | contribs) (→‎Prerequisites: adds link to the legacy SN archive per trac #36009)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search
• 日本語
• 5.19 • 5.2 • 5.3 • 5.8

ServiceNow Integration Configuration

ServiceNow integration allows you to use the Bright Pattern Agent Desktop application within your ServiceNow instance, providing direct access to the phone, live chat, SMS, and other configured messaging capabilities. Through integration, the Agent Desktop application is embedded in ServiceNow as an OpenFrame widget, and there is the option to pop out Agent Desktop in a separate browser tab for full use of activities, cases, interaction details, and more.

ServiceNow integration configuration involves linking your ServiceNow instance to Bright Pattern Contact Center in a ServiceNow integration account.

In this article, you will learn how to:

  • Activate plugins for phone use on ServiceNow
  • Set up OpenFrame
  • Configure system properties, widget properties, page properties, and OpenFrame properties to enable activity history to be saved for interactions handled by the widget
  • Add CORS rules
  • Authorize access to ServiceNow
  • Create a ServiceNow integration account
  • Adjust the display size of Agent Desktop in ServiceNow

Prerequisites

Procedure

For this configuration, we used ServiceNow Paris and Bright Pattern Contact Center version 5.5.5. If you are using an older build of ServiceNow (before Paris), you may want to consult the integration configuration steps for Bright Pattern Contact Center 5.2.

Step 1: Activate plugins for phone communication on servicenow.com

Visit ServiceNow documentation, section Phone installation and configuration, and follow the given procedure, from step 5 to step 7, to activate plugins that establish the phone communication channel between internal and external users and customers.

These steps include the following:

  1. Activate CTI Softphone plugin, which enables OpenFrame to provide softphone functions and call center capabilities like making, receiving, and transferring phone calls.

    Activate CTI Softphone


  2. Activate the Customer Service Management plugin (com.sn_customerservice), which enables additional security.

  3. Activate the OpenFrame plugin, which integrates external communication systems like Bright Pattern Agent Desktop with ServiceNow.

    Activate Openframe plugin


Step 2: Configure System Properties

  1. Go to System Properties by searching for “sys_properties.list” in the ServiceNow admin UI’s Search field.

  2. Then narrow your search by setting the filter to “Name” and searching the system properties for “glide.ui.concourse.onmessage_enforce_same_origin_whitelist.”

    1. If the property does not already exist, click New to create it.

    2. If it already exists and you see it in the list, click into the property to modify it.

      Search system properties for glide.ui.concourse.onmessage_enforce_same_origin_whitelist


  3. In the properties for “glide.ui.concourse.onmessage_enforce_same_origin_whitelist” edit the Value field with your contact center URL in the following format: “https://<tenant_url>.brightpattern.com” (e.g., “https://mycompany.brightpattern.com”). Make sure that the URL begins with “https://” and there is no “/” at the end of it.

    Updating the Value field for glide.ui.concourse.onmessage_enforce_same_origin_whitelist


  4. Click Update.

Step 3: Configure Widget properties

  1. Go to Service Portal > Widgets by searching for “Service Portal” in the ServiceNow admin UI’s Search field and clicking Widgets.

    Use Quick Search to go to Service Portal > Widgets


  2. Click New to create a new widget.

    Click New to create a new widget


  3. In the next step, you will be editing the new widget record with some predefined content from Bright Pattern’s prerequisites archive folder. If you have not already done so, download the prerequisites archive now by clicking Media:Bp_servicenow_integration_2.0.4.zip. Be prepared to open its files and copy/paste them into some of the widget record’s properties.

  4. In the new widget record that opens, set the following properties:

    1. Name - Bright Pattern Open Frame AD Proxy

    2. ID - bpattern_openframe_ad_proxy

    3. Description - The intermediate frame between ServiceNow OpenFrame panel and Bright Pattern AD Communicator widget

      Widget Name, ID, and Description properties


    4. Body HTML template - Open the widget folder from the prerequisites archive, and open the body.html file for editing. Copy the contents of the body.html file and paste it into this field of the new widget record.

      Widget Body HTML template property


    5. CSS - Open the widget folder from the prerequisites archive, and open the css.css file for editing. Copy the contents of css.css and paste it into this field of the new widget record.

      Widget CSS property


    6. Server script - Open the widget folder from the prerequisites archive, and open the server.js file for editing. Copy the contents of the server.js file and paste it into this field of the new widget record.

      Widget Server script property


    7. Client controller - Open the widget folder from the prerequisites archive, and open the client.js file for editing. Copy the contents of the client.js file and paste it into this field of the new widget record.

      Widget Body Client controller property


  5. Click Submit to save your changes to the widget. Widget configuration is now complete.

Step 4: Configure Page properties

  1. Go to Service Portal > Pages by searching for “Service Portal” in the ServiceNow admin UI’s Search field and clicking Pages.

    Use Quick Search to go to Service Portal > Pages


  2. Click New to create a new page.

    Click New to create a new page


  3. On the new page record that opens, you will be editing the new page record with some predefined content from Bright Pattern’s prerequisites archive folder. Be prepared to open its files and copy/paste them into some of the page record’s properties.

  4. Set the following properties:

    1. Title - Bright Pattern Adapter Page for ServiceNow OpenFrame

    2. ID - bpattern_adapter_page

    3. Short description - The HTML page to be embedded into the OpenFrame window for a communication widget

      Page properties Title, ID, and Short description


    4. Page Specific CSS - Open the page folder from the prerequisites archive, and open the css.css file for editing. Copy the contents of css.css and paste it into this field of the new page record.

      Page Specific CSS property


  5. Click Submit to save your changes. The screen will refresh and display the list of available pages.

  6. Note that you will need to re-log your admin user into the ServiceNow application in order to update the widget's access policy settings.

  7. Click on the page you just created (i.e., "bpattern_adapter_page").

    bpattern_adapter_page in the Pages list


  8. Scroll down to the bottom of the page configuration details and click Open in Designer.

    Click Open in Designer to open the Service Portal Designer


  9. A new browser tab or window will open with the Designer widget/page editor such as the one shown.

    Service Portal Designer showing a blank page


  10. With the 'Widgets tab in focus, drag a 12-unit-wide cell from the Layout section on the left and drop it onto the page.

    Click and drag elements onto the Service Portal Designer canvas


  11. Use the Widgets tab search filter to type “Bright Pattern” and find your Bright Pattern Open Frame AD Proxy widget (which was created in the previous step of this procedure) in the Widgets list below the Layouts panel. Then drag and drop it onto the center of the page as you did with the 12-unit cell.

    Click and drag your widget onto the Service Portal Designer canvas


  12. Your changes will be saved automatically, and you can close the Designer editor tab/window now.

  13. To check that the configuration is correct, go back to the page record for bpattern_adapter_page, and scroll down to the Page Content section. You should see the following:

    Page content shown on a page record


Step 5: Edit OpenFrame configuration URL

In this step you will be creating a new OpenFrame configuration with your new page.

  1. Go to OpenFrame > Configurations by searching for “OpenFrame” and clicking Configurations.

  2. In the OpenFrame Configurations list, find the CTI OpenFrame configuration, and click on it to open its properties.

    If there is no existing OpenFrame configuration, click New to create one.

    Use Quick Search to go to OpenFrame > Configurations


  3. To the right of the URL field, click the lock button to edit the URL.

  4. Add the URL for the configuration in the following format:

    https://{your_subdomain}.service-now.com/csm?id={page_id}&bpatternOrigin={tenant_origin}

    In the URL, replace the following with the actual values:

    1. {your_subdomain} - Your ServiceNow subdomain (e.g., “dev97125”)

    2. {page_id} - The page ID (e.g., “bpattern_adapter_page”) that was created in Step 4 of this procedure

    3. {tenant_origin} - The origin of your tenant URL (e.g., “https://mycompany.brightpattern.com”), which is used to open Agent Desktop in iframe

      For example:

      https://dev97125.service-now.com/csm?id=bpattern_adapter_page&bpatternOrigin=https://mycompany.brightpattern.com

      OpenFrame URL property


  5. Click the lock button again to lock the URL.

  6. Make sure that the OpenFrame configuration is still active (see the checkbox for Active at the top of the configuration properties).

  7. Click Update to save your changes.

Step 6: Assign role to allow users to use OpenFrame

The OpenFrame user role called sn_openframe_user is added with activation of OpenFrame. All user accounts need to have the sn_openframe_user role assigned to them in order to use the embedded Agent Desktop. You can assign it to individual users, or to the group of which the users are members.

To assign the role to an individual user:

  1. Go to Organization > Users and click on the name of the user who needs the role.

  2. At the bottom of the user's details, find the Roles tab and click Edit.

  3. Use the filters to search for "sn_openframe_user" and add it to the user's role list.

  4. Click Save.

  5. Repeat for all desired users.


Add role to user's role list


To assign the role to a group:

  1. Go to User Administration > Groups and click on the name of the desired group.

  2. At the bottom of the group's details, find the Roles tab and click Edit.

  3. Use the filters to search for "sn_openframe_user" and add it to the group's role list.

  4. Click Save.

  5. Remember to add users to the group that includes this role.

Step 7: Add CORS Rules

CORS Rules allow Bright Pattern integration accounts to communicate with ServiceNow.

  1. In your ServiceNow instance, go to System Web Services > REST > CORS Rules and click New.

    Add new CORS rules


  2. In Name, enter a unique name (any).

  3. In Domain, enter ​https://<tenant-name>.brightpattern.com, where <tenant-name> is the name of your contact center.

  4. Select HTTP method POST.

    CORS rules and settings


  5. Set HTTP header Access-Control-Allow-Origin.

    HTTP headers


Step 8: Configure a new OAuth 2.0 Endpoint

In order to create a new ServiceNow integration account, you must first configure a new OAuth 2.0 endpoint for ServiceNow. Doing so will provide you with the Client ID and Client Secret, which you will need to authorize access to ServiceNow applications. You will specify the Client ID and Client Secret in your ServiceNow integration account properties in Step 7 of this procedure.

Note that previous builds of ServiceNow may have asked you to configure OAuth. Now ServiceNow recommends you configure OAuth 2.0. For more information, refer to the ServiceNow OAuth Setup documentation.

  1. Make sure the OAuth plugin is active.

    OAuth plugin


  2. Create an endpoint by going to System OAuth > Application Registry and clicking New.

    Add new application registry


  3. Then click Create an OAuth API endpoint for external clients.
    Create the endpoint


  4. Give this registration a name and click Save. The Client ID is filled in for you. The Client Secret will fill upon saving.

    Name the registration and save


  5. Now when you open the application registry you just created, you can view and copy the Client Secret.

Step 9: Create a new integration account

  1. Log in as Admin to the Contact Center Administrator application. Then navigate to Configuration > Integration Accounts.

  2. Click the Add + button to add a new account. In the Create integration account window that appears, select ServiceNow and click OK.

    Select "ServiceNow" as the type of integration account to create


Step 10: Specify ServiceNow integration account properties

Using the My Instance credentials that you saved when you first requested a ServiceNow developer instance, as well as the credentials from OAuth setup, enter values for the following screen properties. (If you do not know your credentials, ask your system administrator.) Be sure to click Apply to save your changes.


ServiceNow integration account properties


  • Type - The type of integration account (i.e., in this case, ServiceNow, which is filled in because you added the account of this type).
  • Name - A unique name (any) for your integration account.
  • Default account - Select this checkbox if this ServiceNow integration account will be used as default.
  • Client ID - The Client ID (string) is the automatically generated unique ID of the application (e.g., "08942j33191d72005a08cb62d2583d6e"). The instance uses the client ID when requesting an access token. Note that the client ID is obtained when configuring the OAuth Endpoint earlier in this procedure.
  • Client Secret - The Client Secret is the shared secret string that both the instance and the application use to authorize communications with one another. The instance uses the client secret when requesting an access token. Note that the client secret is obtained when configuring the OAuth Endpoint earlier in this procedure.
  • Request Refresh Token - This button will request a refresh token. In the dialog that opens, enter the username and password of your ServiceNow instance.
  • Test connection - This button tests the validity of the connection. If the connection is OK, the “Connection is valid” message appears.

Click Apply to save your changes.

Step 11: Authenticate your newly integrated account in ServiceNow

  1. In a separate browser window or tab, go to the ServiceNow Developer site and sign in to your developer instance.

    ServiceNow Developer sign in


  2. Notice that your ServiceNow Homepage now displays a phone icon at the top right corner of the screen.

    You can now make calls from your ServiceNow home page


  3. Click on the phone icon to open the Agent Desktop application widget.

    Log in to Agent Desktop from the integrated widget


Step 12: Resize the Agent Desktop widget (optional)

You can change the width and height of the Agent Desktop widget by adjusting ServiceNow’s OpenFrame configuration properties. Access such configuration settings by searching ServiceNow for “openframe” or by going to ServiceNow’s System Properties > OpenFrame.

The default display size in OpenFrame properties is 373 (W) x 300 (H). In the example shown, we have resized the frame to be 300 (W) x 750 (H).


The widget's width and height are edited in OpenFrame properties


The Agent Desktop widget can be dragged and dropped onto any other part of the webpage.

Step 13: Log in and complete Agent Desktop installation

  1. Sign in to Agent Desktop with your username and password, being sure to select your desired phone device.

  2. By default, you log in with a softphone. To choose another device, click the current Phone device setting and select the desired type of device from the menu that appears. For more information about the available device options, see the Bright Pattern Contact Center Agent Guide, section Selecting a Phone Device.

  3. Click the Login button. Note that if this is your first login into Agent Desktop on the given computer, you will be prompted to install the Agent Desktop Helper Application.


The Bright Pattern Contact Center Agent Desktop widget will now show a standard set of tabs and controls available to a contact center agent.


Tab through to access the dial pad, directory, and more to view previous calls, make calls, and initiate chats


For more information about the Agent Desktop tabs and controls, see the Agent Guide. Note that the appearance and location of these controls has been modified to match the overall look and feel of the ServiceNow application.

You are now able to accept inbound calls and chats, initiate outbound calls and chats, send messages to other contact center users, and more. The integrated Agent Desktop widget will save activity history for all interactions handled via the widget in your ServiceNow environment.


Incoming call on ServiceNow
< Previous | Next >