> For the complete documentation index, see [llms.txt](https://docs.gridmate.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gridmate.io/advanced-guides/grid-actions/grid-command-bridge.md).

# Grid - Command Bridge

Drive an open grid from a Flow, Apex, an integration or an AI agent.

**GridMate - Command Bridge** lets you drive a grid from outside the page. A Flow, Apex code, an integration or an AI agent sends a command, and the grid open in the user's browser runs it right away: search, filter, sort, group, reload, or open its Mass Update or Export dialog.

Every grid type listens on its own: **GM - FieldSet Grid**, **GM - ListView Grid**, **GM - RelatedList Grid** and **GM - User Grid**. There is no component to add and no option to enable.

{% hint style="info" %}
Available from GridMate 12.31.
{% endhint %}

## How it works

1. A publisher creates a **Grid Interaction Event** (`gmpkg__GridInteractionEvent__e`) record. The event names one user and one grid.
2. Every grid on that user's open pages receives the event.
3. A grid runs the command only when the **User Id** is the current user, and **Object Name**, **Grid Name** and **Grid Code** match the grid exactly.

Commands only go one way: nothing is sent back to the publisher. Nothing is saved without the user either. **Mass Update** and **Export** only open their dialogs, and the user confirms there.

## Event fields

| Field          | API name                  | Required         | Value                                                                                                                                    |
| -------------- | ------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| User Id        | `gmpkg__UserId__c`        | Yes              | The **18-character** Id of the user whose open grid should act.                                                                          |
| Command Type   | `gmpkg__CommandType__c`   | Yes              | One of the [commands](#commands) below, for example `applySearch`.                                                                       |
| Grid Name      | `gmpkg__GridName__c`      | Yes              | User Grid: the grid's Developer Name. FieldSet, ListView or RelatedList grid: the field set, list view or related list name.             |
| Grid Code      | `gmpkg__GridCode__c`      | No               | User Grid: its Developer Name again. Other grids: the **DataGrid Code** property. Leave it blank to target a grid with no DataGrid Code. |
| Object Name    | `gmpkg__ObjectName__c`    | Yes, in practice | The API name of the grid's object, for example `Opportunity`. It must match exactly.                                                     |
| Correlation Id | `gmpkg__CorrelationId__c` | No               | A UUID to trace a command in your logs.                                                                                                  |
| Payload Json   | `gmpkg__PayloadJson__c`   | No               | `{"v":1,"args":{...}}`. The `args` depend on the command. Blank means no arguments.                                                      |

{% hint style="warning" %}
**Always set Grid Name.** A grid never acts on an event without one.
{% endhint %}

## Targeting a grid

| Grid on the page                                     | Grid Name                                              | Grid Code               |
| ---------------------------------------------------- | ------------------------------------------------------ | ----------------------- |
| GM - User Grid                                       | Developer Name                                         | Developer Name          |
| GM - FieldSet Grid with DataGrid Code `PIPELINE_CMD` | Field set name, for example `Opportunity_SDR_FieldSet` | `PIPELINE_CMD`          |
| GM - FieldSet Grid without a DataGrid Code           | Field set name                                         | blank                   |
| GM - ListView Grid                                   | List view name, for example `AllOpportunities`         | DataGrid Code, or blank |
| GM - RelatedList Grid                                | Related list name                                      | DataGrid Code, or blank |

{% hint style="info" %}
When the same grid appears twice on a page, give each one a different **DataGrid Code** so a command reaches only one of them.
{% endhint %}

## Commands

| Command Type    | `args`                                                                                 | What the grid does                                                                                                                                                   |
| --------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `applySearch`   | `{"searchTerm":"Steel"}`                                                               | Runs the search on the grid's **Search** fields.                                                                                                                     |
| `applyFilter`   | `{"filterJson":{"and":[{"StageName":{"operator":"=","value":"Negotiation/Review"}}]}}` | Applies an advanced filter, using the same JSON as the [Filter property](https://docs.gridmate.io/advanced-guides/grid-setup/grid-configuration.md#filter-property). |
| `applySort`     | `{"sort":"Amount desc nulls last"}`                                                    | Sorts the grid. Separate several fields with commas. **Temporary**: the saved view is not changed.                                                                   |
| `applyGrouping` | `{"groupBy":"StageName"}`                                                              | Groups the grid. Separate several fields with commas. **Temporary**, like sort.                                                                                      |
| `massUpdate`    | `{}`                                                                                   | Selects every loaded row and opens the **Mass Update** dialog. The user picks the field and value, and confirms.                                                     |
| `exportItems`   | `{}`                                                                                   | Opens the **Export** dialog for the filtered records. The user can choose **Export only selected records**.                                                          |
| `reload`        | `{}`                                                                                   | Reloads the grid's records.                                                                                                                                          |

The grid ignores command types it doesn't know, and payloads that aren't valid JSON.

{% hint style="info" %}
For `applySearch`, the grid needs **Search** fields. Set them with the [Search property](https://docs.gridmate.io/advanced-guides/grid-setup/grid-configuration.md#search-property).
{% endhint %}

## Permissions

* The **GridMate** permission set grants **Read** on Grid Interaction Event. That's all a grid needs to listen.
* **Create** on Grid Interaction Event lets a user or an integration send commands. Grant it only to the users and integration users who should drive grids.
* There is no per-grid opt-in: every grid listens to commands sent by a user with Create access.

## Sending commands

### From a Flow

Use a **Create Records** element on **Grid Interaction Event**, and set the fields above.

{% hint style="warning" %}
In a screen flow:

* Set **User Id** with a formula: `CASESAFEID({!$User.Id})`. The grid needs the 18-character Id.
* A choice picklist can pass its **label** instead of its value. Map the labels to command types with a formula, for example `CASE({!Command}, "Search", "applySearch", "Reload", "reload", {!Command})`, and use that formula for **Command Type**.
  {% endhint %}

### From Apex

```apex
EventBus.publish(new gmpkg__GridInteractionEvent__e(
    gmpkg__UserId__c        = UserInfo.getUserId(),
    gmpkg__CommandType__c   = 'applySearch',
    gmpkg__GridName__c      = 'Opportunity_SDR_FieldSet',
    gmpkg__GridCode__c      = 'PIPELINE_CMD',
    gmpkg__ObjectName__c    = 'Opportunity',
    gmpkg__CorrelationId__c = UUID.randomUUID().toString(),
    gmpkg__PayloadJson__c   = '{"v":1,"args":{"searchTerm":"Steel"}}'
));
```

### From the REST API

```bash
curl -X POST "$INSTANCE_URL/services/data/v64.0/sobjects/gmpkg__GridInteractionEvent__e" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "gmpkg__UserId__c": "005XXXXXXXXXXXXXXX",
    "gmpkg__CommandType__c": "reload",
    "gmpkg__GridName__c": "Opportunity_SDR_FieldSet",
    "gmpkg__GridCode__c": "PIPELINE_CMD",
    "gmpkg__ObjectName__c": "Opportunity",
    "gmpkg__PayloadJson__c": "{\"v\":1,\"args\":{}}"
  }'
```

## Troubleshooting

| Symptom                                   | Check                                                                                                                                                                                                             |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Nothing happens                           | The user has the page open, and **User Id** is that user's 18-character Id. **Grid Name**, **Grid Code** and **Object Name** match the grid exactly. A blank Grid Code only matches a grid with no DataGrid Code. |
| Nothing happens from a screen flow        | **Command Type** receives the picklist label instead of the command. Map it with a formula (see [From a Flow](#from-a-flow)). Reload the page after activating a new flow version.                                |
| Search does nothing                       | The grid has no **Search** fields.                                                                                                                                                                                |
| The publish fails with a permission error | The publisher has no **Create** access on Grid Interaction Event.                                                                                                                                                 |
| The command runs twice                    | Remove **GM - Grid Interaction Bridge** from the utility bar.                                                                                                                                                     |
| Sort or grouping disappears               | Expected: these commands are temporary, and a page reload restores the saved view.                                                                                                                                |

## Next steps

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Field Set Grid</strong></td><td>Build a grid from a field set, filtered to page-related records.</td><td><a href="https://docs.gridmate.io/product-tour/grids/field-set-grid.md">Field Set Grid</a></td></tr><tr><td><strong>Grid - Advanced Configuration</strong></td><td>Generate smart grid property values step by step with the Config Wiz.</td><td><a href="https://docs.gridmate.io/advanced-guides/grid-setup/grid-configuration.md">Grid - Advanced Configuration</a></td></tr><tr><td><strong>Grid - Dynamic Interaction</strong></td><td>Publish grid events so other page components react.</td><td><a href="https://docs.gridmate.io/advanced-guides/dynamic-components/grid-dynamic-interaction.md">Grid - Dynamic Interaction</a></td></tr></tbody></table>

## Command Bridge Demo

After configuring the **GM - Grid Command Console** flow and adding it above a **GM - FieldSet Grid**, you're ready to drive the grid with commands. The video below provides a step-by-step tutorial on how to use the **Grid - Command Bridge** 👇

{% embed url="<https://youtu.be/qhlBrpuDExg>" %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.gridmate.io/advanced-guides/grid-actions/grid-command-bridge.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
