Installing Moveworks for Web on ServiceNow

Installation Participants

On the day of installation, we need these individuals from your team on the call:

ServiceNow admin (able to elevate to the security_admin role)
Testers
Approver to move from test to prod instances

Installation Overview

The call will only take 1 hour to install and run through our test suite.

We will install the prod Moveworks bot into your test ServiceNow environment via update sets.
Once installed, we will run through a test suite designed to test all aspects of Moveworks for Web without overwhelming your team with needing to test core Moveworks features that would already have been tested during your initial Moveworks deployment.
Once tested, we'll ask the approver on the call for permission to move this to your production environment.
- This will be done by promoting the update sets to prod and exporting and importing a few additional records.

At the start of the meeting, Moveworks will send you an encrypted email containing the following:

Java KeyStore certificate and password
Latest base Moveworks update set XML file (if not already installed)
Latest Moveworks for Web update set XML file
Footer HTML snippet

Step 1 - Install the certificate and create the JWT provider

First, we will create a JWT provider in your instance that will be responsible for generating authentication tokens for our services to verify a user is properly authenticated into ServiceNow whenever they visit a page with the Moveworks for Web widget on it. This is what enables Moveworks for Web to automatically log users in. The following steps will walk you through creating the records below:

MW Java Key Store Certificate
JWT Key
JWT Provider

Navigate to the X.509 Certificate table in SNOW (search for "Certificates" to find it), create a new record as follows:

Name: MW Java Key Store

Type: Java Key Store
Click on the paperclip in the upper right to attach the JKS certificate.
Enter the password provided by Moveworks. Right click the top gray bar, click save.
Important: If you save before entering the password, it may seem to auto populate the Key-store password. This doesn't always work correctly, so always enter the password manually.
Click "Validate Stores/Certificates" under Related Links to ensure the record was configured properly.
Navigate to the JWT Keys table (under System Oauth). Create a new record and set its Signing Key Store to the certificate record you made in the previous step. Enter the same password Moveworks provided in the Signing Key field. Save this record.
Navigate to the JWT Provider table. Create a new record and set its Signing Configuration to the key record you made in the previous step.

Important: Copy the sys_id of this JWT Provider record and provide it to your Moveworks Customer Success Team.

Step 2 - Install the base update set

Moveworks offers a number of ServiceNow modules we install into your ServiceNow environment via update sets. If you've previously used other Moveworks modules, you may already have the "base" update set module in place. Verify with your Customer Success Engineer that you have the latest one.

If you need to install the base module, navigate to the Retrieved Update Sets table and click Import Update Set from XML under Related Links.

Upload the base update set file you received in the encrypted email, preview the changes, and commit them.

Important: One of the changes the base update set makes in your environment is adding a moveworks_user role that will allow us to make an API call later to finalize setup. Please navigate to the sys_user table and apply the role to the Moveworks service account.

Step 3 - Install the Moveworks for Web update set

Navigate again to the Retrieved Update Sets table and click Import Update Set from XML under Related Links.

Upload the Moveworks for Web update set (moveworks.webchat.0.0.4.xml), preview the changes, and commit them.

These modules are very self-contained. If you encounter any errors while committing the files, this is usually self-referential and not something to be concerned about. You can usually ignore the warnings and commit the changes.

Note: If you ever need to update a Moveworks module, back out the old update set before importing the new one.

Step 4 - Place the widget on your portal pages

The Moveworks for Web update set makes a widget available in your system that can either be drag and dropped onto individual pages via the Page Designer or placed across multiple portal pages at once by adding a snippet to your portals' theme(s).

We recommend the latter as it is fast and maximizes availability for your users.

Navigate to the sp_portal table. Find the portal(s) on which you'd like to include the widget, and click into its Theme record.

Find the footer field:

If there is nothing there, use the magnifying glass to create a new footer record and navigate to it. If there is already a footer there, navigate to that record.

In the footer record, add this snippet to the Body HTML template field:

<div>
<widget id="mw4web"></widget>
</div>

Ensure the footer is applied to your theme:

Now the widget is set to appear on any page using that theme.

Step 5 - Finalize setup

With this complete, Moveworks will now make an API call to your instance. This will finalize the installation, and anyone granted access from the Moveworks side will start seeing the bot appear on the portal pages.

This API also allows us to make tweaks to the positioning of the bot on the page if necessary (in case it is blocking something else on your page for instance).

Step 6 - Test

Moveworks will walk everyone through about 15 quick test cases to verify the bot behaves as expected.

📘
Note: Our test cases will not produce any tickets. If your team chooses to do additional ad hoc tests, it's worth noting that because we are using a production bot, any tickets your team chooses to file will appear in your production instance, not the test instance in which the widget currently appears.

Step 7 - Promote to production ServiceNow instance

With the tests complete, we like to wrap up the call by promoting the Moveworks for Web to your production instance, so your users can begin enjoying its benefits.

Apply the Moveworks role to the Moveworks service account in prod.
Export the x.509 certificate record, JWT key, and JWT provider record as XML, and import them into their respective tables in prod.
- Follow your standard process for promoting update sets from test to prod, doing so for both the base and Moveworks for Web update sets.
Add the footer and footer snippet to the same themes in prod.

Finally, Moveworks will make one final API call and the installation process to your prod environment is complete.