How to Integrate Retool with Mural

Mural offers two authentication methods for API access: a personal access token (simplest for internal tools) and OAuth 2.0 (required for multi-user applications). For a Retool admin panel used by internal teams, a personal access token is the recommended approach. To generate one, log in to your Mural account and navigate to your profile icon in the top-right corner, then select Developer Settings. In the Developer Settings panel, click Personal Access Tokens, then click Create Token. Give the token a descriptive name like 'Retool Integration'. Select the required scopes: murals:read to retrieve mural lists and widget data, workspaces:read to list workspace rooms and members, and optionally murals:write if your Retool app will create or update murals. Set an expiration period (90 days is a practical default for internal tools, though you can choose longer). Click Create and copy the token immediately — it is only shown once. Store this token in Retool as a Configuration Variable (Settings → Configuration Variables) named MURAL_ACCESS_TOKEN marked as a secret. For teams needing per-user authentication, create an OAuth 2.0 application in Developer Settings instead: provide a Client ID, Client Secret, and set the Redirect URI to your Retool app's domain. OAuth tokens must be refreshed using the refresh_token grant.

With your access token ready, create the Mural REST API Resource in Retool. Navigate to Resources in the left sidebar and click Add Resource. Select REST API from the resource type list. Name the resource 'Mural API'. Set the Base URL to https://app.mural.co/api/public/v1. Under Authentication, select Bearer Token and enter {{ retoolContext.configVars.MURAL_ACCESS_TOKEN }} — this references the Configuration Variable you created, ensuring the token is never exposed in the resource configuration UI. Under Default Headers, add Content-Type: application/json and Accept: application/json. Mural's API follows standard REST conventions with JSON responses. Leave the resource as shared (all Retool users use the same service account token) — this is appropriate for internal ops dashboards. Click Save and use the Test Connection option to verify connectivity. A successful test returns a 200 response. If you see 401, the token may have expired or the Configuration Variable name may be mistyped. If you see 403, the token scopes may be insufficient — return to Mural Developer Settings and verify the selected scopes include murals:read.

With the Resource configured, create the core data-fetching queries. First, create a query named 'getWorkspaceMurals'. Set Method to GET and Path to /workspaces/{{ workspaceIdInput.value }}/murals. Add URL parameters: limit → 50, next → {{ getWorkspaceMurals.data?.next || '' }} for cursor-based pagination. The response returns a value array of mural objects with fields including id, title, createdOn, updatedOn, status, and visitorCount. Create a JavaScript transformer to normalize the response: extract the value array, format timestamps using toLocaleDateString(), and add a computed 'stale' boolean flag (true when the updatedOn date is older than 90 days). Next, create a query named 'getMuralWidgets'. Set Method to GET and Path to /murals/{{ muralsTable.selectedRow.id }}/widgets. This endpoint returns all widgets on the selected mural — sticky notes, text boxes, shapes, images, and connectors. Add URL parameters: limit → 200. In a transformer, filter to only sticky note widgets (where type === 'sticky note' or type === 'sticky'), extract the content text, color hex code, x/y position, and the votes array (each vote has a userId). Compute a voteCount from the votes array length. Return a sorted array with the highest-voted sticky notes at the top. These two queries drive the main dashboard Table components.

1// Transformer: normalize Mural widget data for the Table
2const widgets = data?.value || [];
3const stickyTypes = ['sticky note', 'sticky', 'stickynote'];
4
5return widgets
6  .filter(w => stickyTypes.includes((w.type || '').toLowerCase()))
7  .map(w => ({
8    id: w.id,
9    content: w.htmlContent
10      ? w.htmlContent.replace(/<[^>]+>/g, '').trim()
11      : (w.text || w.title || '(empty)'),
12    color: w.style?.backgroundColor || w.backgroundColor || '#FFEB3B',
13    author: w.createdBy?.name || w.createdBy?.email || 'Unknown',
14    vote_count: Array.isArray(w.votes) ? w.votes.length : 0,
15    x: Math.round(w.x || 0),
16    y: Math.round(w.y || 0),
17    created_at: w.createdOn
18      ? new Date(w.createdOn).toLocaleDateString()
19      : 'N/A'
20  }))
21  .sort((a, b) => b.vote_count - a.vote_count);

With working queries, assemble the analysis dashboard. Start with a Text Input named 'workspaceIdInput' at the top of the canvas for entering the Mural workspace ID, pre-populated with your team's workspace ID. Below it, add a Table component named 'muralsTable' with Data set to {{ getWorkspaceMurals.data }}. Configure columns: title, updatedOn (formatted as date), visitorCount, and a 'Stale?' column using the computed boolean from the transformer (display as a Tag: green 'Active' vs red 'Stale'). Enable row selection on the Table so that clicking a mural triggers the getMuralWidgets query automatically via an event handler (on row select → trigger getMuralWidgets). In the right column, add a second Table named 'widgetsTable' with Data set to {{ getMuralWidgets.data }}. Configure columns: content (wide), color (display as a colored square Tag), vote_count (sortable, default descending), author, and created_at. Above the widgets table, add a Chart component (Bar type) with X-axis set to {{ getMuralWidgets.data.map(w => w.content.slice(0, 30)) }} and Y-axis set to {{ getMuralWidgets.data.map(w => w.vote_count) }} to visualize the voting distribution. Add a stat card row above the chart showing: Total Stickies ({{ getMuralWidgets.data.length }}), Total Votes Cast ({{ getMuralWidgets.data.reduce((sum, w) => sum + w.vote_count, 0) }}), and Unique Authors ({{ new Set(getMuralWidgets.data.map(w => w.author)).size }}). Add a Download CSV button that exports the widget table data using Retool's built-in table export feature.

To make the dashboard actionable for facilitators, add theme grouping and export capabilities. Create a JavaScript query named 'groupByColor' that runs client-side (no resource needed) to group widgets by their background color — which typically represents themes in workshop templates. In the query body, reference getMuralWidgets.data and use Array.reduce() to bucket stickies by their color hex code, computing a count and total votes per color group. Display the color group summary in a small Table or Stat grid above the main widget table, showing: color swatch, count of stickies, and total votes — so facilitators can quickly see which theme generated the most ideas and which got the most votes. Add a Select component that lets users filter widgetsTable by color, using a Table filter with {{ colorFilter.value ? getMuralWidgets.data.filter(w => w.color === colorFilter.value) : getMuralWidgets.data }} as the data source. Finally, add a Form section for documenting session outcomes: a Text Area for 'Key Decisions', a Text Area for 'Next Steps', and a Button that triggers a query to INSERT a workshop_summary row into a connected PostgreSQL table with the mural ID, widget counts, key decisions, next steps, and timestamp. This turns the Retool dashboard into a complete workshop documentation tool.

1// JavaScript query: group sticky notes by color for theme analysis
2const widgets = getMuralWidgets.data || [];
3
4const colorGroups = widgets.reduce((acc, widget) => {
5  const color = widget.color || '#FFEB3B';
6  if (!acc[color]) {
7    acc[color] = { color, count: 0, total_votes: 0, stickies: [] };
8  }
9  acc[color].count += 1;
10  acc[color].total_votes += widget.vote_count;
11  acc[color].stickies.push(widget.content);
12  return acc;
13}, {});
14
15return Object.values(colorGroups)
16  .sort((a, b) => b.total_votes - a.total_votes)
17  .map(group => ({
18    color: group.color,
19    sticky_count: group.count,
20    total_votes: group.total_votes,
21    avg_votes: (group.total_votes / group.count).toFixed(1)
22  }));