> This page is for Assistant Platform. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.moveworks.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.moveworks.com/_mcp/server. # Lab #9: EmployeeWorks Web App > **Info** > > ## Overview > > * **Learning Objectives:** Stand up the EmployeeWorks Web App on your ServiceNow instance: install the ServiceNow applications, connect them to your Moveworks AI Assistant, and test the experience as an employee. > * **Estimated Time:** 45 minutes, plus up to 1 hour for the ServiceNow application install > * **Prerequisites:** > * [Lab #1](/ai-assistant/getting-started/labs/moveworks-setup/lab-1-moveworks-access-sso) through [Lab #8](/ai-assistant/getting-started/labs/moveworks-setup/lab-8-ticketing-core) complete, including Lab #4's user ingestion > * ServiceNow admin credentials for your lab instance --- ### Key Concepts The EmployeeWorks Web App is the EmployeeWorks web experience on your ServiceNow instance, with the Moveworks AI Assistant built in. Employees ask questions, submit forms, and act on their tickets from one page on your ServiceNow instance. * **A surface, not a separate platform:** Everything the EmployeeWorks Web App shows employees comes from the configuration you built in Labs #3 through #8. Knowledge answers come from Lab #6, forms from Lab #7, and ticket actions from Lab #8. If one of those doesn't work in the AI Assistant, it won't work here either. * **Two halves:** You configure one half in **Moveworks Setup** (a dedicated chatbot and the **EmployeeWorks** page) and the other half in **ServiceNow** (two store applications and the Admin Console). * **Trusted Issuer:** ServiceNow signs a token for the logged-in employee, and Moveworks accepts it only from the instance URLs you list as trusted issuers. This is how Moveworks knows which employee is chatting without a second sign-in. * **Identity still matters:** Moveworks matches the employee from ServiceNow against the users ingested in Lab #4. An employee who isn't in **Imported Users** can't use the assistant, even though they can log in to ServiceNow. **Relevant Documentation:** * [Configure EmployeeWorks Web App](/ai-assistant/employeeworks-web-app/configure-employeeworks-on-web) * [ServiceNow Community: EmployeeWorks Web App Implementation Guide](https://www.servicenow.com/community/sn-employeeworks-articles/employeeworks-web-app-implementation-guide/ta-p/3541697) --- ## 🛠️ 1: Walkthrough > **Error** > > **Moveworks Setup does not auto-save.** Click **Save** or **Submit** before you leave any Moveworks Setup page, or you lose your changes. ### 1.1: Install the EmployeeWorks Applications Start this step first. The install runs in the background while you complete Sections 1.2 and 1.3. 1. In ServiceNow, navigate to **System Applications > All Available Applications > All** 2. Search for **EmployeeWorks Web App** 3. Install both applications: | **Application** | **Scope** | **Purpose** | | ---------------------------------- | ------------------- | ---------------------------------------- | | **EmployeeWorks Web App** | `sn_ex_emp_hub_mw` | Required. The core experience. | | **EmployeeWorks Web App Extended** | `sn_ex_emp_hub_adv` | Adds Announcements and the App Launcher. | 4. When prompted, select **Load Demo Data** > **Warning** > > **The install can take up to an hour, and it blocks other installs.** While it runs, ServiceNow rejects update set previews and commits with "another operation is running." Don't retry the install. Check progress in **System Applications > All Available Applications > All** and wait for the status to show installed. > **Note** > > **Can't find the applications?** Search for `EmployeeWorks`. If nothing similar appears under **All**, your instance isn't entitled to the applications. Contact your ILT host. --- ### 1.2: Create the EmployeeWorks Chatbot The EmployeeWorks Web App needs its own chatbot record in Moveworks Setup. Don't edit the chatbot your tenant already has. 1. In Moveworks Setup, navigate to **Chat Platforms > Manage Chatbots > Chatbots** 2. Open your tenant's existing webchat chatbot (its **Bot Name** ends in `-webchat`) and note its **Select Connector** value. Don't change anything on this record. 3. Go back to the list and click **Create** 4. Enter the values below 5. Click **Save** | **Field Name** | **Action / Value to Enter** | | ------------------------------------------- | -------------------------------------------------------------------------------------- | | **Channel** | `movewebchat` | | **Select Connector** | The same connector as your existing `-webchat` chatbot (the value you noted in step 2) | | **Bot ID** | `1234` (Moveworks replaces this with a generated ID when you save) | | **Bot Name (Moveworks Identifier)** | `[your-org]-employeeworks-webchat` | | **Bot Friendly Name** | Your AI Assistant's name, as employees should see it | | **Channel Configurations** | `Movewebchat Vars` | | **Channel Configurations > Webchat App ID** | `1234` | | **Channel Configurations > Surface** | `unified-frontdoor` | ![](/_fern-files/_img/dcef389f1c8749f5dab62fe7da136b17ce3bc482a840a8b9916d8203cb3362e0.webp) ![](/_fern-files/_img/66ad893828acea6c06aa68d8bfa491c09f6bb4acd958f18acac0d07ade08bfed.webp) > **Error** > > **The Bot Name can't be changed after you save, and it must end in `-webchat`.** Moveworks generates the chatbot's ID from the name, so a typo means creating a new chatbot. Check the name before you click **Save**. > **Error** > > **Create a new chatbot. Don't reuse or edit the existing webchat chatbot.** Changing the existing chatbot's **Surface** breaks the assistant everywhere that chatbot is used. > **Warning** > > **Surface must be `unified-frontdoor`.** If you leave it blank, it defaults to `embedded` and the EmployeeWorks Web App won't connect. --- ### 1.3: Configure the EmployeeWorks Page This page tells Moveworks which ServiceNow instance to trust and what to show on the EmployeeWorks home page. 1. In Moveworks Setup, navigate to **Chat Platforms > EmployeeWorks** 2. Under **Connector and Trusted Issuer**, add a group: * **Select your connector:** `snow` (the connector from Lab #3) * **Add Trusted Issuer:** your ServiceNow instance URL, `https://[your-instance].service-now.com` 3. Under **Universal Assistant Suggested Prompts**, add up to four prompts that employees can click on the home page. Each prompt has two fields: * **Display Text:** the label under the chat bar, 16 characters maximum * **Utterance:** the full message sent when an employee clicks the prompt, 130 characters maximum 4. Optionally, set **Universal Assistant Input Placeholder Text**: the hint shown in the chat bar before an employee types, 130 characters maximum 5. Click **Submit** ![](/_fern-files/_img/d789997513afbd80344d4ed8a3f3af4130687f4e1b285a99c9bc70ea2a6b4809.webp) > **Error** > > **The Trusted Issuer must exactly match the instance the connector points to, with no trailing slash.** `https://[your-instance].service-now.com/` fails. A group whose connector and trusted issuer reference different instances also fails, and both mistakes show up later as a `401` error with no other clue. Example suggested prompts built on the earlier labs: | **Display Text** | **Utterance** | | ----------------- | ----------------------------------------- | | `Reset password` | `How do I reset my password?` | | `New laptop` | `I need a new laptop` | | `My tickets` | `Show me my open tickets` | | `Report an issue` | `I want to report an issue with my email` | --- ### 1.4: Configure the Experience in the Admin Console Continue once the install from Section 1.1 has finished. 1. In ServiceNow, navigate to **Admin > Admin Home** ![](/_fern-files/_img/dc1caef019d82063f88a43b5566fe0829c9e1b944261af3cbb5ab01be7888a49.webp) 2. Under **Manage your products**, click the **Employee Slate for Moveworks** card. This is the EmployeeWorks Web App product. ![](/_fern-files/_img/cb0bafeeed7c49a5fa0b44fc5053550c59f6ec5cc656d8892aad7cd273ff12e1.webp) 3. Confirm both applications show **Installed**, then click **Configure** ![](/_fern-files/_img/1714df6ff569db79206c310ed8d1c322d9693a85771ff0aef53feda28125fbb9.webp) #### Conversational Assistant (required) 1. Under **Conversational assistant**, open **Moveworks setup** 2. In **Moveworks instance**, enter your Moveworks AI Assistant instance URL: the base URL of your tenant, with no trailing slash 3. Click **Save** To find your tenant URL, open Moveworks Setup and copy the address bar up to and including `moveworks.com`. ![](/_fern-files/_img/6cb8f6cfe5e9299f4084568ac5bfd830f634b242389765a10aefce3592bbf6aa.webp) > **Warning** > > **Use the base URL only, with no trailing slash.** Include `https://` and stop at `moveworks.com`. A wrong URL leaves the assistant area of the page blank. #### Appearance (recommended) 1. Under **Appearance**, open **Branding and theming** 2. Enter a **Name** for the portal, and optionally upload a logo and choose colors 3. Use the preview to check desktop and mobile, light and dark modes 4. Save the module ![](/_fern-files/_img/438226edb090b35fe045c4fdb02d07b1d1b0a4de7f6131af84e5c884e7bbf5c6.webp) > **Note** > > **The other modules are optional for this lab.** Homepage Widgets, the Canvas Widget Library, Tasks & Requests, and Email Notifications all work with their defaults. The [Implementation Guide](https://www.servicenow.com/community/sn-employeeworks-articles/employeeworks-web-app-implementation-guide/ta-p/3541697) covers each module, plus taxonomy, communication banners, and URL rewrite rules. --- ## ✅ 2: Verification & Testing ### 2.1: Confirm the Test User Don't test as `admin` or another built-in account. Built-in accounts usually aren't in the Moveworks user roster, so the assistant can't identify them and doesn't load. 1. Use the personal user you created in Lab #2, or a teammate's 2. In Moveworks Setup, navigate to **Core Platform > User Identity > Imported Users** and search for that user 3. Confirm the user appears in the results > **Note** > > **Users created after Lab #4 aren't in Imported Users yet.** Ingestion runs about every four hours. Pick a user who was active when Lab #4 ran, or wait for the next ingestion. ### 2.2: Open the EmployeeWorks Web App 1. In ServiceNow, impersonate the test user from Section 2.1 2. Navigate to `https://[your-instance].service-now.com/aiux/employeeworks/home` 3. Confirm the home page loads with your portal name and the suggested prompts from Section 1.3 ![](/_fern-files/_img/1e24b6a3aeb8488d9a8b739c534ed6c162956e2ac042b6e2d5be705d77f1a3c9.webp) ### 2.3: Exercise the Earlier Labs Each test below exercises one lab through the EmployeeWorks Web App: | **Test** | **Try** | **Expected Result** | **Exercises** | | ---------------- | --------------------------------------------- | ---------------------------------- | ------------- | | Knowledge | Ask a question your knowledge base answers | An answer with a source citation | Lab #6 | | Forms | `I need a new laptop` | A catalog form you can submit | Lab #7 | | Ticketing | File a ticket, then ask for your open tickets | The ticket is created, then listed | Lab #8 | | Suggested prompt | Click one of your prompts | The utterance is sent and answered | Section 1.3 | > **Note** > > **A test that fails here and also fails in your AI Assistant is a gap in the earlier lab, not in the EmployeeWorks Web App.** Fix it in that lab, then retest. ### 2.4: Troubleshooting | **Symptom** | **Likely Cause** | **How to Check** | | ----------------------------------------------------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Page doesn't load at all | Wrong URL | Use `https://[your-instance].service-now.com/aiux/employeeworks/home` | | Page loads but the assistant area is blank | Testing as `admin` or a user who isn't in Imported Users | Impersonate a user who appears in **Imported Users** (Section 2.1) | | `401` error in the browser console on a request to `/auth/` | Trusted Issuer missing, mismatched, or ending in `/` | In **Chat Platforms > EmployeeWorks**, confirm the group's connector and trusted issuer reference the same instance, with no trailing slash | | Assistant area is blank, no errors in the console | Wrong URL in the Conversational Assistant module, or an outdated application version | Recheck the URL from Section 1.4. If it's correct, update both EmployeeWorks applications to the latest version in **System Applications > All Available Applications > All** | | Chatbot won't save | Bot Name doesn't end in `-webchat`, or Bot ID isn't a number | Use `[your-org]-employeeworks-webchat` and Bot ID `1234` | | Applications not found | Searched for an older name, or no entitlement | Search for `EmployeeWorks`. If nothing appears, contact your ILT host | | Update set commit fails with "another operation is running" | The application install is still running | Wait for the install to finish, then retry | | No knowledge answers | Lab #6's initial ingestion hasn't finished (about 12 hours) | Ask the same question in your AI Assistant. If it fails there too, wait or revisit Lab #6 | | Can't file or view tickets | Lab #8 ticketing configuration | Test ticket actions in your AI Assistant. If they fail there, revisit Lab #8 | > **Success** > > **You've completed the core Moveworks Setup labs!** Next, pick any of the [optional labs](/ai-assistant/getting-started/labs/moveworks-setup), or start the [Tool Studio Quickstart series](/tool-studio/quickstart-guide/purple-api-tool) to build plugins on your configured Moveworks instance. Start with the Purple API Tool to set up your shared session, then work through Quickstart #1. --- ## 🪞 3: Reflecting on This Configuration Through this lab, you've learned the following: * How the EmployeeWorks Web App sits on top of the Moveworks platform you configured in Labs #3 through #8 * How to install the EmployeeWorks applications and configure them from the ServiceNow Admin Console * How to create a dedicated `unified-frontdoor` chatbot without disturbing the existing webchat chatbot * How the Connector and Trusted Issuer group lets Moveworks identify the employee signed in to ServiceNow * Why testing as a normal, ingested user matters, and how to split a failure between the platform and the experience How this will come up during live implementations: * **Validate the platform first.** Run the checklist on [Configure EmployeeWorks Web App](/ai-assistant/employeeworks-web-app/configure-employeeworks-on-web) before touching the experience. Most "EmployeeWorks is broken" reports are a missing platform layer. * **Plan for every ServiceNow environment.** The connector, identity, knowledge, forms, and ticketing configuration, plus the application install and update sets, repeat for each ServiceNow environment. Each environment also needs its own Connector and Trusted Issuer group. See [Deploy to Multiple ServiceNow Environments](/ai-assistant/employeeworks-web-app/deploy-to-multiple-servicenow-environments). * **Customer instances may have run an older Moveworks web widget.** If a `moveworks.webchat` update set is present, back it out before installing the EmployeeWorks applications. Otherwise the install skips records and the experience doesn't render. * **Promote configuration, don't rebuild it.** The Admin Console's **Package and download** option exports your experience configuration as an update set for moving from staging to production. --- ## ⚙️ 4: Configuration Summary | **Component** | **Where** | **What** | | ---------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------- | | **EmployeeWorks Web App** application | ServiceNow > System Applications > All Available Applications > All | Installed with demo data | | **EmployeeWorks Web App Extended** application | ServiceNow > System Applications > All Available Applications > All | Installed | | **EmployeeWorks chatbot** | Moveworks Setup > Chat Platforms > Manage Chatbots > Chatbots | New chatbot, name ending `-webchat`, Surface `unified-frontdoor` | | **Connector and Trusted Issuer** | Moveworks Setup > Chat Platforms > EmployeeWorks | `snow` connector + instance URL, no trailing slash | | **Suggested prompts** | Moveworks Setup > Chat Platforms > EmployeeWorks | Up to 4 prompts | | **Conversational Assistant** | ServiceNow > Admin > Admin Home > Employee Slate for Moveworks > Configure | Moveworks tenant base URL | | **Appearance** | ServiceNow > Admin > Admin Home > Employee Slate for Moveworks > Configure | Portal name, logo, colors | | **Home page** | `https://[your-instance].service-now.com/aiux/employeeworks/home` | Tested as a normal, ingested user |