Connect custom actions and products

Use this advanced guide when your application needs operations beyond the built-in grid actions. A prepared action produces a preview first and commits only when the user selects Apply. A product adapter exposes operations owned by an existing Pivot, Gantt, Scheduler or Kanban instance.

Complete the quick start first. The examples below extend that configuration and assume your application already owns the referenced services or product instances.

Custom prepared actions

For persisted data, preview through your existing service and commit only after approval:

import { actionInput, defineAiPreparedAction } from '@revolist/revogrid-pro';

const updateOrder = defineAiPreparedAction({
  name: 'orders.update',
  description: 'Preview and update an authorized order.',
  inputSchema: orderUpdateSchema, // Your bounded JSON Schema.
  revision: () => [orders.version],
  parse(input) {
    const value = actionInput(input, ['id', 'amount']);
    return validateOrderUpdate(value); // Your typed validation.
  },
  async prepare(input, { signal }) {
    const proposal = await orders.preview(input, { signal });
    return {
      preview: {
        summary: 'Update order amount',
        changes: [{
          item: proposal.orderName,
          label: 'Amount',
          before: proposal.currentAmountLabel,
          after: proposal.proposedAmountLabel,
        }],
      },
      async apply({ signal }) {
        signal.throwIfAborted();
        await orders.commit(proposal.token, { signal });
        return { message: 'Order updated.' };
      },
    };
  },
});
// Register with grid.aiAssistant.actions: [updateOrder].

orders, its schema and validation are application-owned. Preparation must not mutate data. The server must recheck authorization and version when committing. Bound and localize preview text, honor cancellation before side effects, and supply actionHistory only when your service supports undo/redo. defineAiAction supports immediate operations through the same typed registry. Keep names unique.

Approved integration recipes accept only { recipe: 'approved-id' }. Configure formulas.apply, data.import, data.export, charts.open, pivot.configure or backend.run in integrations, with host-owned preview/apply callbacks. The model cannot invent a formula, URL, upload or callback. Recipes own their actual feature integration and disclosure policy; downloads and chart openings are not automatically undoable edits.

Native product adapters

Product guides: Pivot · Pivot Charts · Gantt · Event Scheduler · Kanban.

Use the adapter from the product that owns the data, rather than applying flat-grid operations to a projection:

import { createPivotAiActions, createPivotChartsAiActions } from '@revolist/pivot';
import { createGanttAiActions } from '@revolist/gantt';
import { createSchedulerAiActions } from '@revolist/scheduler';
import { createKanbanAiActions } from '@revolist/kanban';

Adapter	Operations	Explicit opt-ins
createPivotAiActions(pivotPlugin, options)	pivot.configure, pivot.read	Disclosed fields and readRows for aggregate reads.
createPivotChartsAiActions(chartsPlugin, options)	pivotCharts.inspect, pivotCharts.update	Explicit chart IDs, metadata inspection and allowed chart types/settings/series.
createGanttAiActions(ganttPlugin, options)	gantt.readTasks, gantt.getChildren, gantt.updateTask	Allowed read/update fields and optional per-task permission checks.
createSchedulerAiActions(schedulerPlugin, options)	scheduler.readEvents, scheduler.selectEvents, scheduler.updateEvent	Allowed read/update fields, selection policy and optional per-event permission checks.
createKanbanAiActions(kanbanPlugin, options)	kanban.readCards, kanban.selectCards, kanban.updateCard, kanban.moveCards	Disclosed card fields, typed update fields, allowed destinations and per-card permissions.

Add the returned actions to aiAssistant.actions and allow their schemas in your server interpreter. Reads are bounded to 50 records at most. Mutations use native APIs and preview approval. Do not register a recipe with the same action name. See the adapter implementations and colocated tests for product-specific field and permission types.

Kanban example

See the Kanban AI guide for the operation inputs, permissions, history and remote-board limits.

import { createKanbanAiActions } from '@revolist/kanban';
import type { AiAssistantConfig } from '@revolist/revogrid-pro';

const aiAssistant: AiAssistantConfig = {
  interpret, // Your API-client adapter from the quick start.
  fields: [],
  executor: {
    read: () => ({ sort: [] }),
    async apply() {
      throw new Error('Use the native Kanban actions for this board.');
    },
  },
  actions: createKanbanAiActions(kanbanPlugin, {
    read: { fields: ['id', 'title', 'status'], maxCards: 20 },
    select: {},
    update: { fields: { title: 'string', priority: 'number' } },
    move: { columns: ['todo', 'doing', 'done'] },
  }),
};
// Assign aiAssistant to your existing assistant host's configuration.

This action-only setup disables flat-grid view mutations: native products own their projection, filtering and sorting. Use an empty field policy and an executor that rejects view commands instead of attaching the default flat-grid executor. Use your board’s real field and column IDs. Reads expose only permitted scalar fields from filter-visible loaded cards (including collapsed columns and lanes), with at most 50 cards per result; they are not a complete remote-dataset query. Selection uses native card selection. Updates and moves are prepared actions with Apply/Cancel through the existing shared assistant UI. They are registered only for local boards without configured persistence. Remote or persisted boards can use reads/selection; writes require application-owned actions.

Native Kanban owns edit permissions, transition rules, WIP limits, rank ordering, events and history. A move on a board with a swimlane field must specify swimlaneId; allowed columns/swimlanes and permission callbacks can narrow the policy. Identity, ordering and location cannot be changed through scalar update fields. This adapter does not add card creation/deletion, filtering, highlighting or column presentation controls.

The reference backend recognizes these four action names but its fixture field policy is for orders. Replace that policy with your own server-approved board metadata before connecting business cards. Recognizing an action descriptor does not authorize data access.

Next: Work with server-side data.