Lab #6b: Moveworks Bender
Overview
- Learning Objectives: Understand how to leverage Moveworks Bender to configure attribute mappings for users and tickets. Use the DSL & Bender Mapper Playground to validate configurations before applying them.
- Estimated Time: 15 minutes
- Prerequisites:
- Lab 1 complete (snow connector with sys_user access)
- Lab 2 complete (user identity configured — provides the Bender mapping to test against)
Key Concepts
Bender is the transformation engine that sits between connected raw system data and the Moveworks UI. It is essential for formatting data correctly:
- Bender Mapping: The logic used to tell Moveworks how to display raw JSON values. For example, turning a technical “state” code into a human-readable word.
- Display Value: A ServiceNow-specific concept where
valueis a raw ID (e.g., a sys_id) anddisplay_valueis the actual text shown to the user. - Fallback Logic: The use of the
ORoperator (e.g.,phone.display_value OR "") to provide a default value and prevent the bot from breaking if a field is empty. - DSL & Data Mapper Playground: A sandbox where you can paste raw JSON from the API Playground to test if your Bender mappings will work before applying them. Relevant Documentation:
- Moveworks Help: Bender Data Mapping
- Moveworks Help: DSL & Data Mapper Playground
- Moveworks Agent Marketplace: Agent Architect
🛠️ 1: Walkthrough
1.1: Generate a Moveworks API Key via Agent Studio
- Navigate to the
HTTP Connectorspage via the Waffle Menu to generate a Moveworks API Key
- Select the
Credentialsmodule
- Click
Create
- Give your credential a name, and generate it as an
API KeyandPublishit
- Select
Copy to Clipboard, and store this API key on your machine.
- In a separate tab, navigate to the Moveworks DSL and Data Mapper Playground. Enter your API key in the
API Keysection.
Note: If you receive an error that states that an on-prem agent cannot connect, try opening the page in an incognito browser window and try again
1.2: Get the Default Bender Mapping for Moveworks ServiceNow User Identity
- In Moveworks Setup, navigate to
User Identity > Import Users > Edit
- Now that we have confirmed we can see users, we will use the following configuration example in
Advanced Modeto grab the JSON block representing the configuration for ingesting users from ServiceNow
- Copy the JSON block that defines the ServiceNow User Ingestion Logic (Also available below)
- Paste it into the Mappers section of the DSL & Bender Playground
- Navigate to API Playground, and query a user record, then copy an instance of the user record
Note: We’re using a single record here to mirror how Moveworks actually works. The system maps records one by one. Comparing your configuration against a single instance is the best way to preview how the data will look once it’s ingested.
- Copy this JSON into the Input Payload for the DSL and Mapper Playground
- Click
Processand see how the bender mapping is applied to the input payload!
Note: To ensure your Moveworks object representation is accurate, use this iterative process during the build phase. Always verify that fields are populating exactly as intended by following these steps:
- Retrieve a sample record from your external system.
- Configure the Bender to map your required fields.
- Validate the mapping results within the DSL and Data Mapper tool.
1.3: Leverage Moveworks DSL Architect for Creating New Bender Mappings
Note: The Moveworks Agent Architect is an AI powered tool connected to Moveworks documentation. The DSL Architect can help you write DSL & Bender logic for all of your configurations!
- Navigate to the Moveworks Agent Architect and select the DSL Architect
- Provide the DSL Architect with the input mapping and what your stated goal is, leverage the following example
Based on the following input payload, please generate a complete, valid Bender mapping in both JSON and YAML formats. I am using this for a class, so please include a brief HTML introduction explaining the concepts covered. Specifically, I need the following 5 complex data transformation examples included in the mapping:
- String Templating (user_summary): Use RENDER() to create a sentence combining calendar_integration.display_value and sys_updated_on.display_value.
- Conditional Logic (security_risk_assessment): Use EVAL() with an IF/THEN/ELSE statement to return ‘High Risk’ if both enable_multifactor_authn.value and web_service_access_only.value are ‘false’, otherwise ‘Standard’.
- Risk Score (risk_score): Use the CONDITIONAL() operator to return 100 if enable_multifactor_authn.value is ‘false’, and 0 if it passes.
- Time Parsing (last_login_epoch): Use EVAL() and $PARSE_TIME() to convert last_login_time.value into an epoch timestamp.
- Data Fallbacks (location_info): Use COALESCE() to return the first available value among building.display_value, country.display_value, or a hardcoded string ‘“Unknown Location”’. Please ensure the JSON is fully closed and valid. Here is the payload:
- This will allow Agent Architect to give us an initial JSON construction for us to use in our mapping. Once it has provided it, we will want to
copythe Bender JSON
- And then we can paste it into the Editor section and see how how it would transform how our user is mapped within the Moveworks User Roster!
✅ 2: Verification & Next Steps
- Finalize:
- Confirm that the JSON mapping processes successfully without errors.
- Inspect:
- Analyze the functions and dot-walking logic used in the Editor section of the Data Mapping Playground. Review how these functions transform the input and why the resulting output appears the way it does.
- Experiment:
- Modify the Input Payload and Editor values to see how the output changes. Try incorporating different logic or nested fields to test the limits of the mapping.
- Reference:
- Consult the Bender Guide on the Moveworks Help Site for a full list of available Bender Functions to expand your toolkit.
- Leverage the Moveworks DSL Architect for advise on complex bender configurations that you want to do for an instance.
🪞 3: Reflecting on This Configuration
Through this guide, you’ve learned the following:
- How to leverage the DSL & Data Mapper Playground
- Where to pull existing configuration JSON values from to test how the configuration will be applied
- API Playground (Resource)
- User Identity or Ticketing Configuration (Bender Mapping)
- Where to find additional examples of the Moveworks Bender language & associated functions
- How to use the Moveworks Agent Architect to help write complex bender mappings
🧠 4: Knowledge Check: Lab #6b
1. Based on the ServiceNow JSON structure, why do we use .display_value in our Bender mappings instead of just the field name?
- Answer: ServiceNow stores data in objects where
valueis often a raw ID (like a sys_id) or a code, whiledisplay_valuecontains the human-readable string. 2. In the following Bender snippet from your lab, what is the purpose of theOR ""?$TRIM(IF phone THEN phone.display_value OR "" ELSE NULL) - Answer: It provides a fallback to an empty string to prevent the mapping from failing or returning an error if the
display_valueproperty is missing. 3. Which Moveworks tool should you use if you want to test how a specific user’s raw ServiceNow data will look after being processed by your Bender configuration? - Answer: The DSL and Data Mapper Playground.
4. True or False: The
RENDER()function is used for mathematical calculations like risk scores. - Answer: False.
RENDER()is used for string templating to create human-readable sentences. (Bonus:CONDITIONAL()orEVAL()would be used for scores).
⚙️ 5: Configuration Details
Use the table below to fill in the required fields accurately.