---
availability: INSTALLABLE
name: Create a Break-Fix Case
description: Lets retail store employees report broken in-store equipment in seconds from the Moveworks AI Assistant — no portal form, no help desk call.
installation_asset_uuid: 8f58b8df-0d78-4edd-9665-e834c1416ffc
purple_chat_link: https://marketplace.moveworks.com/purple-chat?conversation=%7B%22messages%22%3A%5B%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22I+need+to+report+a+broken+barcode+scanner+at+my+store.+It%27s+urgent+and+customers+are+lining+up+at+cash+counter%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22Identifying+user%27s+retail+store+location...%22%2C%22connectorName%22%3A%22servicenow%22%7D%2C%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22Searching+for+barcode+scanners+at+%3Cb%3ESolana+San+Diego%3C%2Fb%3E...%22%2C%22connectorName%22%3A%22servicenow%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EI%27ve+identified+your+store+as+%3Cstrong%3ESolana+San+Diego%3C%2Fstrong%3E.+I+found+three+barcode+scanners+registered+there.%3C%2Fp%3E%3Col%3E%3Cli%3EZebra+DS2208+Handheld+Barcode+Scanner%3C%2Fli%3E%3Cli%3EHoneywell+Voyager+1202g+Wireless+Scanner%3C%2Fli%3E%3Cli%3EDatalogic+QuickScan+QD2590+Imager%3C%2Fli%3E%3C%2Fol%3E%3Cp%3EWhich+one+is+having+issues%3F%3C%2Fp%3E%22%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22It%27s+1%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22Retrieving+asset+details+for+Zebra+DS2208...%22%2C%22connectorName%22%3A%22servicenow%22%7D%2C%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22Drafting+urgent+break-fix+incident+request...%22%2C%22connectorName%22%3A%22servicenow%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EGot+it.+Since+customers+are+lining+up+and+it%27s+urgent%2C+I%27ve+mapped+this+to+%3Cstrong%3EP1+%28Critical%29%3C%2Fstrong%3E+priority.%3C%2Fp%3E%3Cp%3EHere+is+a+summary+of+your+break-fix+request+for+%3Cstrong%3EServiceNow%3C%2Fstrong%3E%3A%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cstrong%3EStore%3A%3C%2Fstrong%3E+Solana+San+Diego%3C%2Fli%3E%3Cli%3E%3Cstrong%3EEquipment%3A%3C%2Fstrong%3E+Zebra+DS2208+Handheld+Barcode+Scanner%3C%2Fli%3E%3Cli%3E%3Cstrong%3EPriority%3A%3C%2Fstrong%3E+P1+%28Critical%29%3C%2Fli%3E%3Cli%3E%3Cstrong%3EIssue+Title%3A%3C%2Fstrong%3E+Zebra+DS2208+Scanner+broken%3C%2Fli%3E%3Cli%3E%3Cstrong%3EDescription%3A%3C%2Fstrong%3E+Scanner+is+broken+and+customers+are+lining+up+at+cash+counter.%3C%2Fli%3E%3C%2Ful%3E%3Cp%3E%3Cstrong%3EReady+to+submit%3F%3C%2Fstrong%3E%3C%2Fp%3E%22%7D%2C%7B%22buttons%22%3A%5B%7B%22buttonText%22%3A%22Yes%22%2C%22style%22%3A%22filled%22%7D%2C%7B%22buttonText%22%3A%22Cancel%22%2C%22style%22%3A%22outlined%22%7D%5D%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Yes%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22Creating+break-fix+case+in+%3Cb%3EServiceNow%3C%2Fb%3E...%22%2C%22connectorName%22%3A%22servicenow%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EYour+break-fix+case+%3Ca+href%3D%5C%22https%3A%2F%2Fservicenow.com%5C%22%3ERBF0006790%3C%2Fa%3E+has+been+created.+Your+case+is+in+the+queue+for+%3Cb%3EHQ+Facilities%3C%2Fb%3E.+You+will+get+a+notification+when+it+is+assigned.%3C%2Fp%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22servicenow%22%2C%22citationTitle%22%3A%22RBF0006790%22%7D%5D%7D%5D%7D%5D%7D
solution_tags:
- Support
- Facilities
- Retail Operations
- Retail Store Services
- RSM
- Store Operations
systems:
- servicenow
---
# Introduction
Frontline retail store employees can report broken in-store equipment — scanners, printers, registers, and more — right from the Moveworks AI Assistant, without navigating the ServiceNow RSM portal, filling out a form, or calling the help desk. Reporting an issue takes seconds, an optional photo can be attached, and duplicate reports for the same device are caught before a second ticket is opened.
For store operations and facilities teams, this means faster reporting of equipment issues, less store downtime, and a cleaner case queue free of duplicate tickets — turning a multi-step portal task into a few seconds of conversation.
# User Experience Preview
Please refer to the following [**Purple Chat**](https://marketplace.moveworks.com/purple-chat?conversation=%7B%22messages%22%3A%5B%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22I+need+to+report+a+broken+barcode+scanner+at+my+store.+It%27s+urgent+and+customers+are+lining+up+at+cash+counter%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22Identifying+user%27s+retail+store+location...%22%2C%22connectorName%22%3A%22servicenow%22%7D%2C%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22Searching+for+barcode+scanners+at+%3Cb%3ESolana+San+Diego%3C%2Fb%3E...%22%2C%22connectorName%22%3A%22servicenow%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EI%27ve+identified+your+store+as+%3Cstrong%3ESolana+San+Diego%3C%2Fstrong%3E.+I+found+three+barcode+scanners+registered+there.%3C%2Fp%3E%3Col%3E%3Cli%3EZebra+DS2208+Handheld+Barcode+Scanner%3C%2Fli%3E%3Cli%3EHoneywell+Voyager+1202g+Wireless+Scanner%3C%2Fli%3E%3Cli%3EDatalogic+QuickScan+QD2590+Imager%3C%2Fli%3E%3C%2Fol%3E%3Cp%3EWhich+one+is+having+issues%3F%3C%2Fp%3E%22%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22It%27s+1%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22Retrieving+asset+details+for+Zebra+DS2208...%22%2C%22connectorName%22%3A%22servicenow%22%7D%2C%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22Drafting+urgent+break-fix+incident+request...%22%2C%22connectorName%22%3A%22servicenow%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EGot+it.+Since+customers+are+lining+up+and+it%27s+urgent%2C+I%27ve+mapped+this+to+%3Cstrong%3EP1+%28Critical%29%3C%2Fstrong%3E+priority.%3C%2Fp%3E%3Cp%3EHere+is+a+summary+of+your+break-fix+request+for+%3Cstrong%3EServiceNow%3C%2Fstrong%3E%3A%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cstrong%3EStore%3A%3C%2Fstrong%3E+Solana+San+Diego%3C%2Fli%3E%3Cli%3E%3Cstrong%3EEquipment%3A%3C%2Fstrong%3E+Zebra+DS2208+Handheld+Barcode+Scanner%3C%2Fli%3E%3Cli%3E%3Cstrong%3EPriority%3A%3C%2Fstrong%3E+P1+%28Critical%29%3C%2Fli%3E%3Cli%3E%3Cstrong%3EIssue+Title%3A%3C%2Fstrong%3E+Zebra+DS2208+Scanner+broken%3C%2Fli%3E%3Cli%3E%3Cstrong%3EDescription%3A%3C%2Fstrong%3E+Scanner+is+broken+and+customers+are+lining+up+at+cash+counter.%3C%2Fli%3E%3C%2Ful%3E%3Cp%3E%3Cstrong%3EReady+to+submit%3F%3C%2Fstrong%3E%3C%2Fp%3E%22%7D%2C%7B%22buttons%22%3A%5B%7B%22buttonText%22%3A%22Yes%22%2C%22style%22%3A%22filled%22%7D%2C%7B%22buttonText%22%3A%22Cancel%22%2C%22style%22%3A%22outlined%22%7D%5D%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Yes%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22Creating+break-fix+case+in+%3Cb%3EServiceNow%3C%2Fb%3E...%22%2C%22connectorName%22%3A%22servicenow%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EYour+break-fix+case+%3Ca+href%3D%5C%22https%3A%2F%2Fservicenow.com%5C%22%3ERBF0006790%3C%2Fa%3E+has+been+created.+Your+case+is+in+the+queue+for+%3Cb%3EHQ+Facilities%3C%2Fb%3E.+You+will+get+a+notification+when+it+is+assigned.%3C%2Fp%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22servicenow%22%2C%22citationTitle%22%3A%22RBF0006790%22%7D%5D%7D%5D%7D%5D%7D) for a sample conversational experience between a user and the AI Assistant for this plugin.
# Pre-requisites
Before installing and using the **Create Break-Fix Case** plugin, please ensure the following requirements are met:
## **1. ServiceNow Retail Store Services Application**
This plugin operates on the **Retail Store Services** break-fix case table (`sn_rtl_stre_servcs_bf_case`) and its supporting CSM tables (`sn_csm_service_organization_member`, `sn_install_base_item`). The **Retail Store Services** application must be installed and active on your ServiceNow instance before installing this plugin.
Install it from the ServiceNow Store: [**Retail Store Services**](https://store.servicenow.com/store/app/f84516ce1b87e210c43e65b2604bcb7a)
## **2. User Identity Ingestion from ServiceNow**
This plugin opens each case under the **requesting user's own ServiceNow identity**. The `opened_by` field is populated by dot-walking the user's profile in the Data Bank:
`opened_by: meta_info.user.external_system_identities.snow.external_id`
This reads the user's ServiceNow `sys_id` from the identity source linked to their Moveworks profile, so your users **must be ingested from ServiceNow** for this value to populate. To set up user identity for your org, read our help docs on [**Identity Configuration in Moveworks Setup**](https://help.moveworks.com/service-management/moveworks-setup/identity-configuration).
> ⚠️ **Important — update this mapping to match your setup.** The `snow` key in that path must exactly match the name of **your** ServiceNow identity source in Moveworks Setup. If yours is named differently (e.g. `servicenow_prod`), update the Compound Action mapping to `meta_info.user.external_system_identities.servicenow_prod.external_id`. If it doesn't match, the path resolves to **`null`** and case creation fails with a missing `opened_by`.
> ✅ **No mapping changes needed for `meta_info.user.email_addr`.** This plugin also uses the user's email (ex: to resolve their authorized retail stores). Unlike the ServiceNow ID above, `meta_info.user.email_addr` is a **standard, top-level Moveworks user attribute** — it works out-of-the-box for every customer as long as user ingestion is set up from **any** source (Okta, Microsoft Graph, ServiceNow, etc.). No customer-specific customization is required.
## **3. ServiceNow Connectors**
This plugin uses **two** ServiceNow connectors side by side:
**Connector 1 — OAuth 2.0 Authorization Code (user-based / User Consent auth).** Used for every call in this plugin *except* case creation itself: the store lookup, device lookup, duplicate check, and the optional attachment upload all execute under the **authenticated user's own ServiceNow identity**, respecting each user's existing ServiceNow roles and ACLs. Set this up following the [**OAuth 2.0 Authorization Code guide**](https://marketplace.moveworks.com/connectors/servicenow#oauth-2-0-authorization-code).
**Connector 2 — OAuth 2.0 Client Credentials (non-user / service account).** Used **only** for the case-creation POST. This call runs under a **dedicated service account**, scoped to a role limited to retail break-fix operations only (no standing access beyond what this plugin needs). Set this up following the [**OAuth 2.0 Client Credentials guide**](https://marketplace.moveworks.com/connectors/servicenow#oauth-2-0-with-client-credentials).
Both connectors must be fully set up before installing this plugin.
Once configured, follow our [**plugin installation documentation**](https://help.moveworks.com/docs/ai-agent-marketplace-installation) for detailed steps on how to install and activate the plugin in **Agent Studio**.
# **How This Plugin Works**
The plugin identifies the user's store automatically from their store membership, asking them to pick only if they belong to more than one. It then has the user choose the affected device, describe the issue, set a priority, and optionally attach a photo. Before creating the case, it checks for an existing open case on that device (treating a Resolved-but-not-Closed case as a duplicate too) and returns the existing case instead of opening a second one. The user reviews a summary — store, device, issue, priority, and attachment — and confirms before anything is created.
# **Implementation Details**
## API Details
All calls run against the customer's ServiceNow instance. Replace `YOUR_INSTANCE` with your ServiceNow instance hostname and `ACCESS_TOKEN` with the access token for the connector noted on each call — the authenticated user's OAuth token (Connector 1) for every call except case creation, and the service account's Client Credentials token (Connector 2) for the create call only.
### **API #1: Resolve the User's Store(s)** *(Connector 1 — user-based)*
Returns the service-organization membership rows for the requesting user. When exactly one row is returned, the store slot fills silently; otherwise the user picks.
```bash
curl --location 'https://YOUR_INSTANCE/api/now/table/sn_csm_service_organization_member?sysparm_query=user.email=<USER_EMAIL>&sysparm_display_value=true' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
--header 'Accept: application/json'
```
**Parameters:**
- `USER_EMAIL` *(string):* The requesting user's email (`meta_info.user.email_addr`).
### **API #2: Resolve Install-Base Items for the Store** *(Connector 1 — user-based)*
Returns the devices/equipment registered to the resolved store, scoped by the store reference.
```bash
curl --location 'https://YOUR_INSTANCE/api/now/table/sn_install_base_item?sysparm_query=<STORE_SCOPE_QUERY>&sysparm_display_value=true' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
--header 'Accept: application/json'
```
**Parameters:**
- `STORE_SCOPE_QUERY` *(string):* Encoded query scoping install-base items to the resolved store.
### **API #3: Duplicate-Case Check** *(Connector 1 — user-based)*
Checks for an open break-fix case on the chosen `install_base` item. Excludes terminal states (Closed = `3`, Cancelled = `7`). Limited to 1 result.
```bash
curl --location 'https://YOUR_INSTANCE/api/now/table/sn_rtl_stre_servcs_bf_case?sysparm_query=install_base=<INSTALL_BASE_SYS_ID>^stateNOT IN3,7&sysparm_limit=1&sysparm_display_value=true' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
--header 'Accept: application/json'
```
**Parameters:**
- `INSTALL_BASE_SYS_ID` *(string):* `sys_id` of the chosen install-base item.
**Key nuances:**
- If this call returns a row, the plugin returns the existing case and never runs the create POST.
### **API #4: Create the Break-Fix Case** *(Connector 2 — service account)*
Creates the case on `sn_rtl_stre_servcs_bf_case`. This is the **only** call in the plugin that runs under the service-account connector rather than the requesting user's own session. `contact_type` is set to `moveworks` so the source of creation is auditable.
```bash
curl --location 'https://YOUR_INSTANCE/api/now/table/sn_rtl_stre_servcs_bf_case' \
--request POST \
--header 'Authorization: Bearer ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"short_description": "{{short_description}}",
"description": "{{description}}",
"install_base": "{{install_base_sys_id}}",
"requesting_service_organization": "{{store_sys_id}}",
"priority": "{{priority}}",
"opened_by": "{{requesting_user_sys_id}}",
"contact_type": "moveworks"
}'
```
**Parameters:**
- `priority` *(string, optional):* `1` (Critical), `2` (High), `3` (Moderate), `4` (Low). Omit to fall back to ServiceNow's default priority calculation.
- `opened_by` *(string, required):* Must be explicitly set to the requesting user's sys_id. Because this call runs under the service-account connector, there is no user session for ServiceNow to infer it from — omitting it would attribute the case to the service account instead of the actual requester.
### **API #5: Upload Attachment (Optional)** *(Connector 1 — user-based)*
Attaches the user's file to the created case. If this call fails, the case is preserved and `attachment_warning` is surfaced — the attachment failure does **not** roll back the case.
```bash
curl --location 'https://YOUR_INSTANCE/api/now/attachment/upload' \
--request POST \
--header 'Authorization: Bearer ACCESS_TOKEN' \
--header 'Content-Type: multipart/form-data' \
--form 'table_name=sn_rtl_stre_servcs_bf_case' \
--form 'table_sys_id={{case_sys_id}}' \
--form 'uploadFile=@{{file}}'
```
### API References
For detailed information on request parameters, response formats, and error handling, refer to the official [**ServiceNow Table API**](https://docs.servicenow.com/bundle/latest-application-development/page/integrate/inbound-rest/concept/c_TableAPI.html) and [**Attachment API**](https://docs.servicenow.com/bundle/latest-application-development/page/integrate/inbound-rest/concept/c_AttachmentAPI.html) documentation.
# **What Is In Scope for This Plugin?**
- Submitting new break-fix cases for in-store equipment.
- Auto-resolving the user's store (prompting when they belong to more than one).
- Capturing store, device, priority, a short and long description, and an optional attachment.
- Detecting and blocking duplicate cases for the same device when an open (non-terminal) case already exists.
# **What Is Out of Scope for This Plugin?**
- Tracking, viewing, or updating existing break-fix cases (handled by **Get Break-Fix Case Details** and **Update Break-Fix Case**).
- Fulfillment, assignment, or resolution of cases.
- Adding comments, extending due dates, or reassigning fulfillers on existing cases.
- Bulk creation of multiple break-fix cases in a single utterance.
- Opening a case on behalf of another user (the case is always opened by the requesting user).
# Related Plugins
| Plugin | What it does |
|--------|-------------|
| [Get Break-Fix Case Details](https://marketplace.moveworks.com/plugins/servicenow-retail-get-breakfix-case-details) | Look up the status, assignee, and details of an existing break-fix case by number or description. |
| [Update Break-Fix Case](https://marketplace.moveworks.com/plugins/servicenow-retail-update-breakfix-case-details) | Add comments, reopen, close, accept, or reject a resolution on an existing case. |
| [Notify Requesters of Break-Fix Case Updates](https://marketplace.moveworks.com/plugins/servicenow-retail-notify-on-breakfix-case-updates) | Push proactive notifications to the Moveworks AI Assistant when a case is assigned, needs more info, or is resolved. |