> This page is for Tools. > 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. # Built-in Actions # Using Built-in Actions Moveworks provides built-in actions for common platform operations — user lookups, notifications, approvals, and LLM generation. These are ready to use without creating connectors or HTTP actions. When you want to use a built-in action in your [Compound Action](/tool-studio/actions/compound-actions), use `mw.{{action_name}}` as your `action_name`. For example: ```yaml - action: action_name: mw.get_user_by_email output_key: user_result input_args: user_email: meta_info.user.email_addr ``` # Action Reference ## `get_user_by_email` Retrieve a single user record by email address. Returns all user attributes including custom attributes. **Action Name:** `mw.get_user_by_email` **Input Parameters:** | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ----------------------------------------- | | `user_email` | string | Yes | The email address of the user to retrieve | **Example:** ```yaml - action: output_key: user_result action_name: mw.get_user_by_email input_args: user_email: meta_info.user.email_addr ``` **Response Schema:** ```json { "user": { "full_name": "John Doe", "email_addr": "john.doe@moveworks.ai", "record_id": "10769610738892443", "department": "Engineering", ... } } ``` **Reference:** `data.user_result.user.email_addr`, `data.user_result.user.full_name`, etc. You can find the full list of user fields in our [User Attribute Reference](/platform-management/user-identity/user-attribute-reference). --- ## `batch_get_users_by_email` Retrieve multiple users by email in a single call. Use this when you need to resolve several users (e.g., an approver and a requester). **Action Name:** `mw.batch_get_users_by_email` **Input Parameters:** | Parameter | Type | Required | Description | | ------------- | ------------- | -------- | -------------------------------------------- | | `user_emails` | List\[string] | Yes | The email addresses of the users to retrieve | > **Info** > > Results are returned **in the same order** as the input email list. If you pass `["manager@example.com", "employee@example.com"]`, then `user_records[0]` is the manager and `user_records[1]` (or `user_records[-1]`) is the employee. **Example:** ```yaml - action: output_key: target_users action_name: mw.batch_get_users_by_email input_args: user_emails: - data.manager_email - data.employee_email ``` **Response Schema:** ```json { "user_records": [ { "lookup_id": "12345", "user": { "full_name": "John Doe", "email_addr": "john.doe@moveworks.ai", "record_id": "10769610738892443", ... } }, { "lookup_id": "67890", "user": { "full_name": "Jane Smith", "email_addr": "jane.smith@moveworks.ai", "record_id": "10769610738892444", ... } } ] } ``` **Reference:** `data.target_users.user_records[0].user` for the first user, `data.target_users.user_records[-1].user` for the last. You can find the full list of user fields in our [User Attribute Reference](/platform-management/user-identity/user-attribute-reference). --- ## `create_generic_approval_request` Create a Moveworks in-bot approval request. The compound action pauses execution until the approval is answered (up to 30 days). **Action Name:** `mw.create_generic_approval_request` **Input Parameters:** | Parameter | Type | Required | Description | | --------------------- | ----------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `approval_details` | string | Yes | The details that need approval | | `users_requested_for` | List\[User] | Yes | Users who the approval is being requested for | | `approvers` | List\[User] | No | Users from whom to get approval. Reaches out to all; only one approval needed. Overrides `approval_key` if provided. | | `approval_key` | string | No | The approval key describing the workflow. If omitted, must provide `approvers`. [Supported Keys](/service-management/approval-workflow/moveworks-setup-native-approval-settings) | | `title` | string | No | Title of the approval request | > **Pass User objects, not emails.** > > `approvers` and `users_requested_for` require User objects, not email strings. Retrieve user objects first using [`mw.get_user_by_email`](#get_user_by_email) or [`mw.batch_get_users_by_email`](#batch_get_users_by_email). **Example:** ```yaml - action: output_key: approval_result action_name: mw.create_generic_approval_request input_args: title: '''Access to Coupa Request''' approval_details: '''Need access to Coupa for procurement workflow''' approvers: - data.manager_user.user users_requested_for: - data.requesting_user.user progress_updates: on_pending: Sending approval request... on_complete: Approval received. ``` **Response Schema (Approved):** ```json { "status": "APPROVED", "approved_by": [ { "full_name": "John Doe", "record_id": "10769610738892443", "email_addr": "john@moveworks.ai", "comment": "Looks good, approved." } ], "state": { "initial_status": "PROCESSING", "status": { "john@moveworks.ai": "APPROVED" } } } ``` **Response Schema (Denied):** ```json { "status": "DENIED", "denied_by": [ { "full_name": "John Doe", "record_id": "10769610738892443", "email_addr": "john@moveworks.ai", "comment": "Budget not available for Q2." } ], "state": { "initial_status": "PROCESSING", "status": { "john@moveworks.ai": "DENIED" } } } ``` **Reference:** `data.approval_result.status` returns `"APPROVED"` or `"DENIED"` (uppercase). To access the approver/denier's comment (e.g., a denial justification): ```yaml # Access the denial comment message: data.approval_result.denied_by[0].comment # Access an approval comment message: data.approval_result.approved_by[0].comment ``` > **Info** > > To enable a **Deny with Comment** button on the approval card, configure the approval buttons in [Moveworks Setup > Approval Settings](/service-management/approval-workflow/moveworks-setup-native-approval-settings). This can be set at the integration level or global level. --- ## `batch_send_plaintext_chat_notification` Send a chat notification to one or more users. Use with `batch_get_users_by_email` to resolve user record IDs first. **Action Name:** `mw.batch_send_plaintext_chat_notification` **Input Parameters:** | Parameter | Type | Required | Description | | --------------- | ------------- | -------- | ----------------------------------------------------------------------------------------------- | | `notifications` | List\[object] | Yes | Array of notification objects, each containing `user_record_id` (string) and `message` (string) | **Example:** ```yaml - action: output_key: target_users action_name: mw.batch_get_users_by_email input_args: user_emails: - '''alice@example.com''' - '''bob@example.com''' - action: action_name: mw.batch_send_plaintext_chat_notification output_key: notification_result input_args: notifications: MAP(): items: data.target_users.user_records converter: user_record_id: item.user.record_id message: '''Please complete your quarterly review.''' ``` **Response Schema:** ```json { "user_notification_tracker_details": [ { "notification_tracker_uuid": "abc-123-def" } ] } ``` > **Info** > > For sending interactive notifications with action buttons, use the [`notify` compound action expression](/tool-studio/actions/compound-actions/notify) instead. --- ## `generate_text_action` Generate free-form text output using an LLM. Use for summarization, classification, formatting, and other text generation tasks. **Action Name:** `mw.generate_text_action` **Input Parameters:** | Parameter | Type | Required | Description | | ---------------------------- | ------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- | | `user_input` | string | Yes | The input text for the LLM to process | | `system_prompt` | string | No | Instructions for how the LLM should behave | | `model` | string | No | Model to use (default: `gpt-5.4-mini`) | | `temperature` | number | No | Sampling temperature (0-2) | | `image` | List\[File] or File | No | Optional image input(s) for multimodal processing. We recommend `gpt-5` or newer | | `file` | List\[File] or File | No | Optional document input(s) — PDF, spreadsheets, rich documents, presentations, and text/code. We recommend `gpt-5` or newer | | `reasoning_effort` | string | No | `"minimal"` (gpt-5 only), `"low"`, `"medium"`, or `"high"` (reasoning models only) | | `enable_web_search` | boolean | No | Enable the live web search tool to include current web information in the model's context | | `web_search_allowed_domains` | List\[str] | No | Restrict web search to these domains (up to 100). Enables web search automatically | | `web_search_blocked_domains` | List\[str] | No | Exclude these domains from web search (up to 100). Enables web search automatically | **Example:** ```yaml - action: action_name: mw.generate_text_action output_key: summary_result input_args: system_prompt: '''Summarize the following text in 2-3 sentences.''' user_input: data.article_content model: '''gpt-5.4-mini''' ``` **Response:** `data.summary_result.generated_output` (string) For full reference including supported models, see [LLM Actions](/tool-studio/actions/llm-actions). --- ## `generate_structured_value_action` Generate structured JSON output matching a defined schema. Use for classification, entity extraction, and any task where you need typed output. **Action Name:** `mw.generate_structured_value_action` **Input Parameters:** | Parameter | Type | Required | Description | | ---------------------------- | ------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- | | `payload` | object | Yes | The input data for the LLM to process | | `output_schema` | string | Yes | JSON Schema defining the expected output structure. Must include `additionalProperties: false` on all objects. | | `system_prompt` | string | No | Instructions for how the LLM should behave | | `model` | string | No | Model to use (default: `gpt-5.4-mini`) | | `strict` | string | No | Enforce strict schema adherence. Defaults to `false` | | `image` | List\[File] or File | No | Optional image input(s) for multimodal processing. We recommend `gpt-5` or newer | | `file` | List\[File] or File | No | Optional document input(s) — PDF, spreadsheets, rich documents, presentations, and text/code. We recommend `gpt-5` or newer | | `reasoning_effort` | string | No | `"minimal"` (gpt-5 only), `"low"`, `"medium"`, or `"high"` (reasoning models only) | | `enable_web_search` | boolean | No | Enable the live web search tool to include current web information in the model's context | | `web_search_allowed_domains` | List\[str] | No | Restrict web search to these domains (up to 100). Enables web search automatically | | `web_search_blocked_domains` | List\[str] | No | Exclude these domains from web search (up to 100). Enables web search automatically | **Example:** ```yaml - action: action_name: mw.generate_structured_value_action output_key: classification_result input_args: payload: data.customer_review system_prompt: '''Analyze the sentiment of this review.''' output_schema: >- { "type": "object", "properties": { "sentiment": {"type": "string", "enum": ["positive", "negative", "neutral"]}, "confidence": {"type": "number"} }, "required": ["sentiment", "confidence"], "additionalProperties": false } ``` **Response:** `data.classification_result.generated_output` (object matching your schema) For full reference including supported models, see [LLM Actions](/tool-studio/actions/llm-actions).