>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3588789. --> Reported by: [ajv009](https://www.drupal.org/user/3653917) >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>Acquia Source's JSON:API for media images does not expose <code>drupal_internal__mid</code> (the numeric media ID) by default. Canvas page inputs require this numeric <code>target_id</code>, so agents must either parse it from the self-link URL or request it explicitly. Both sessions that hit this issue independently discovered the same workaround.</p> <p>The media handler uploads images and then needs to supply a numeric <code>target_id</code> for each image to the Canvas page component inputs. The standard approach &mdash; reading <code>drupal_internal__mid</code> from the JSON:API response &mdash; silently returns nothing on Acquia Source. The <code>target_id</code> field ends up empty or zero, causing Canvas page images to render broken or missing without an obvious error. The issue was independently encountered in both an efi-ed-source Q1 session and an edu-site-mockup-ai session, making it a reliable recurrence pattern on any Acquia Source migration. The workaround is known (parse from self-link URL or use explicit <code>?fields</code> parameter), but it is not in any agent file.</p> <p>Root cause: Acquia Source configures its JSON:API module to suppress <code>drupal_internal__mid</code> (the internal Drupal entity ID for media) from the default attributes response. This is an Acquia SaaS platform configuration decision, likely to avoid exposing internal IDs in the public API. However, Canvas page component inputs use the numeric <code>target_id</code> to reference media entities. The UUID is not a substitute &mdash; Canvas page inputs require the numeric ID. There are two workarounds:</p> <ul> <li><strong>Option A &mdash; Explicit field request:</strong> append <code>?fields[media--image]=drupal_internal__mid</code> to the media GET request, which forces Acquia to include the field.</li> <li><strong>Option B &mdash; Self-link URL parse:</strong> read <code>response.data.links.self.href</code>, which contains <code>resourceVersion=id%3A&lt;N&gt;</code> where <code>&lt;N&gt;</code> is the numeric MID in URL-encoded form. Decode and parse.</li> </ul> <h4 id="summary-steps-reproduce">Steps to reproduce</h4> <ol> <li>Upload an image via the standard JSON:API media POST.</li> <li>Read <code>response.data.attributes.drupal_internal__mid</code>.</li> <li>Observe: the attribute is <code>undefined</code>/absent.</li> <li>Use the (empty) value as <code>target_id</code> in a Canvas page input.</li> <li>Observe: the page image renders as broken/missing on the live site, with no obvious error.</li> </ol> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <p>Document the workaround in <code>.claude/agents/media-handler.md</code>, in any media upload script (e.g., <code>scripts/upload-media.mjs</code>), and in <code>docs/migration/gotchas.md</code>. No platform code change is proposed &mdash; the field suppression is an Acquia configuration; the agent must work around it.</p> <p><strong>Step 1 &mdash; Add a "MEDIA ID LOOKUP" block to <code>.claude/agents/media-handler.md</code>:</strong></p> <pre>MEDIA ID LOOKUP &mdash; drupal_internal__mid: Acquia Source does NOT expose drupal_internal__mid in the default JSON:API media response. Do NOT use response.data.attributes.drupal_internal__mid &mdash; it will be absent (undefined/empty). Two workarounds (use either): Option A &mdash; Explicit field request: GET /api/media/image/&lt;UUID&gt;?fields[media--image]=drupal_internal__mid This forces Acquia to include the field. Option B &mdash; Self-link URL parse: From the upload POST response, read response.data.links.self.href The URL contains: resourceVersion=id%3A&lt;N&gt; URL-decode: id%3A&lt;N&gt; &rarr; id:&lt;N&gt; N is the numeric drupal_internal__mid (target_id). Example parse (JavaScript): const selfHref = response.data.links.self.href; const match = selfHref.match(/resourceVersion=id%3A(\d+)/); const mid = match ? parseInt(match[1], 10) : null;</pre><p><strong>Step 2 &mdash; Update the media upload script (e.g., <code>scripts/upload-media.mjs</code> if present)</strong> to apply the Option B parse immediately after the upload POST call so <code>mid</code> is always captured at upload time and does not require a follow-up GET request. Option B is preferred for efficiency &mdash; Option A requires an extra HTTP round trip.</p> <p><strong>Step 3 &mdash; Add to <code>docs/migration/gotchas.md</code>:</strong> "<code>drupal_internal__mid</code> is not in the default JSON:API media response on Acquia Source. Two fixes: (A) <code>?fields[media--image]=drupal_internal__mid</code> on the GET, or (B) parse <code>resourceVersion=id%3A&lt;N&gt;</code> from the self-link. See media-handler.md &sect; Media ID Lookup."</p> <h3 id="summary-remaining-tasks">Remaining tasks</h3> <ul> <li>Add the MEDIA ID LOOKUP block to <code>.claude/agents/media-handler.md</code>.</li> <li>Update the media upload script (confirm filename &mdash; likely <code>scripts/upload-media.mjs</code>) to apply Option B parse at upload time.</li> <li>Add the gotchas.md entry.</li> <li>Verify: <code>grep -n "drupal_internal__mid" .claude/agents/media-handler.md</code> returns the workaround instruction.</li> <li>Verify: <code>grep -n "resourceVersion" .claude/agents/media-handler.md</code> returns the self-link parse pattern.</li> <li>Verify: if <code>scripts/upload-media.mjs</code> exists, <code>grep -n "resourceVersion" scripts/upload-media.mjs</code> returns the parse code.</li> <li>Confirm whether the existing <code>media-map.md</code> (if used) has its <code>target_id</code> column populated by the self-link parse at upload time; if currently blank, the script change is the correct place to populate it.</li> </ul> <h3 id="summary-ui-changes">User interface changes</h3> <p>None directly. Indirectly: pages that consume media references will render their images instead of rendering broken/missing.</p> <h3 id="summary-api-changes">API changes</h3> <p>None at the Drupal/Canvas platform level. Two existing JSON:API capabilities are documented as canonical: the <code>?fields[media--image]=drupal_internal__mid</code> sparse-fieldset request (Drupal core JSON:API feature), and the self-link URL parse (a stable property of the JSON:API self-link format).</p> <h3 id="summary-data-model-changes">Data model changes</h3> <p>None. New documentation in agent file and gotchas.md, plus an in-script parse update if the upload script exists.</p> <h3 id="summary-internal-references">Internal references</h3> <ul> <li>Source markdown: <code>RESEARCH-2026-04-28/99-final/ISSUES/Sprint-5-Drupal-Canvas-Gotchas/05-P2-10-drupal-internal-mid-not-in-json-api.md</code> (id: P2-10)</li> <li>Consolidated issues: <code>RESEARCH-2026-04-28/99-final/consolidated-issues.md</code> &sect; P2-10</li> <li>Actionable list: <code>RESEARCH-2026-04-28/99-final/actionable-list.md</code> &sect; P2-10</li> <li>Q1 discovery (efi-ed): <code>RESEARCH-2026-04-28/03-efi-ed-source/Q1-records-1-to-2884/issues-found.md</code> Bug 6</li> <li>Independent re-discovery: <code>RESEARCH-2026-04-28/02-edu-site-mockup-ai/fc6fc3db/issues-found.md</code> ISSUE-7</li> <li>Note: this gotcha is not in <code>acquia-cms-gotchas.md</code> &sect; G1-G19 catalog. Consider adding as G20.</li> </ul> <h3 id="summary-open-questions">Open questions</h3> <ul> <li>Is the upload script called <code>upload-media.mjs</code> or something else? Check <code>package.json</code> scripts for the media upload command name.</li> <li>Does the current media-handler store <code>target_id</code> in <code>media-map.md</code>? If yes, confirm that the map's <code>target_id</code> column gets populated by the self-link parse at upload time. If currently blank, the script change is the correct place to populate it.</li> <li>Option A (explicit <code>?fields</code> GET) requires an additional HTTP request after upload. Option B (self-link parse) works from the upload response alone. Option B is preferred for efficiency &mdash; surface this choice in the implementation note.</li> </ul>