@@ -0,0 +1,17 @@
+---
+'@object-ui/types': minor
+'@object-ui/data-objectstack': minor
+'@object-ui/plugin-grid': patch
+'@object-ui/i18n': patch
+'@object-ui/app-shell': patch
+---
+
+The import wizard's "Download template" button now downloads the server's import template, an Excel workbook, instead of building a CSV of every field (objectui#9600).
+
+The old CSV listed every field the wizard was handed, including the system and read-only columns every object carries (created by, owner, and so on). The server strips those columns on import without an error, so a user who filled them in lost that data silently. The server's template (`GET /api/v1/data/:object/export?template=true`, objectstack 17.6.0) lists only the columns this caller can import. It marks required ones with `*`, adds dropdowns for select and boolean columns, and includes an instructions sheet.
+
+- **`@object-ui/types`: new optional `DataSource.downloadImportTemplate(resource)`**, resolving to the template file as a `Blob`. Additive. When a data source lacks it, no template is offered: there is no client-side fallback.
+- **`@object-ui/data-objectstack`: `ObjectStackAdapter.downloadImportTemplate(resource)`** sends `template=true` on the export route, on the same request path as `exportDownload`. When the client has a locale set (`getClient().setLocale`), the request carries it as `Accept-Language`, the way the import request does. The template's labels are written in the request's locale, and the import accepts a translated label only in its own request's locale, so the two requests must match.
+- **`@object-ui/plugin-grid`: `ImportWizard` offers the template** when its data source has `downloadImportTemplate` and the user can create records of the object (`usePermissions().can(object, 'create')`, the server's own gate). A 405 (object not open for import), a 403 (no create permission) and any other failure each show a message on the upload step, and no file is saved. The client-built CSV is deleted, with its helpers (`buildImportTemplateCsv`, `exampleForField`, `firstOptionValue`, `downloadTextFile`). The column mapping step is unchanged.
+- **`@object-ui/app-shell`**: the identity-import data source (`sys_user`) withholds `downloadImportTemplate`, because the server's template describes the generic import door, not the identity pipeline.
+- **`@object-ui/i18n`**: `grid.import.downloadTemplateHint` describes the Excel template in all ten packs, and `grid.import.templateDownloadFailed` and `grid.import.templateNotPermitted` are new.
@@ -255,6 +255,14 @@ describe('createIdentityImportDataSource — saved mappings are expressed, not i
       expect(typeof ds[withheld]).not.toBe('function');
     }
   });
+
+  it('withholds the generic import template even when the base carries it as an own property (objectui#9600)', () => {
+    // A plain-object base: the spread WOULD copy an own method across, so this
+    // arm is the one that fails without the explicit `undefined`. The template
+    // describes the object's generic import door, not the identity pipeline.
+    const ds = wrap({ downloadImportTemplate: async () => new Blob(['x']) });
+    expect(typeof ds.downloadImportTemplate).not.toBe('function');
+  });
 });
 
 /**
 
@@ -245,6 +245,11 @@ export function createIdentityImportDataSource(opts: IdentityImportDataSourceOpt
     listImportJobs: undefined,
     cancelImportJob: undefined,
     undoImportJob: undefined,
+    // The server's import template describes the GENERIC import door of the
+    // object (objectui#9600), not the identity pipeline this wrapper writes
+    // through, whose target set is curated (`identityImportFields`). The
+    // wizard offers the template only when this method is a function.
+    downloadImportTemplate: undefined,
     // Saved mappings ARE offered for identity import — director-seat ruling,
     // decision batch #68 (objectui#7740, comment 5565349507; ledger on
     // objectstack#12708). Importing users benefits from saved field mappings
 
@@ -0,0 +1,182 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * `ObjectStackAdapter.downloadImportTemplate` (objectui#9600) — the import
+ * wizard's 「下载模板」 request: `GET /api/v1/data/:object/export?template=true`.
+ *
+ * Three things are pinned:
+ *  - the wire: the export route, `template=true` and nothing else (the server
+ *    refuses the export's row parameters on a template request);
+ *  - the locale: the server writes the template's labels in the request's
+ *    locale, and the import accepts a translated label only in its OWN
+ *    request's locale. So the template request must carry the same
+ *    `Accept-Language` the import request does. Asserted as parity against the
+ *    real `importRecords` request, through the same `fetch`, in both states of
+ *    the client locale;
+ *  - the refusals the server answers a template with: 403 `PERMISSION_DENIED`
+ *    (no create permission, ADR-0112 nested envelope) and 405
+ *    `OBJECT_API_METHOD_NOT_ALLOWED` (object not open for import, flat
+ *    dialect). Both reach the caller as `code` + `status`.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { ObjectStackAdapter } from './index';
+
+type FetchSpy = ReturnType<typeof vi.fn<(url: string, init: RequestInit) => Promise<Response>>>;
+
+function makeDS(fetchImpl: FetchSpy, baseUrl = 'http://test.local') {
+  const ds: any = new ObjectStackAdapter({ baseUrl, fetch: fetchImpl as any });
+  ds.connected = true;
+  ds.connectionState = 'connected';
+  return ds;
+}
+
+const xlsxResponse = () =>
+  new Response('xlsx-bytes', {
+    status: 200,
+    headers: { 'Content-Type': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' },
+  });
+
+/** Read one header off a recorded `init`, whatever shape its headers took. */
+function headerOf(init: RequestInit | undefined, name: string): string | null {
+  return new Headers(init?.headers as HeadersInit | undefined).get(name);
+}
+
+describe('ObjectStackAdapter.downloadImportTemplate — the wire', () => {
+  it('GETs the export route with template=true and no other parameter', async () => {
+    const fetchImpl: FetchSpy = vi.fn(async () => xlsxResponse());
+    const ds = makeDS(fetchImpl);
+
+    const blob = await ds.downloadImportTemplate('task');
+
+    expect(blob).toBeInstanceOf(Blob);
+    expect(await blob.text()).toBe('xlsx-bytes');
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchImpl.mock.calls[0];
+    const parsed = new URL(url);
+    expect(parsed.pathname).toBe('/api/v1/data/task/export');
+    expect([...parsed.searchParams.entries()]).toEqual([['template', 'true']]);
+    expect(init.method).toBe('GET');
+    expect(init.credentials).toBe('include');
+  });
+
+  it('does not double the version segment when the base URL already ends in /api/v1', async () => {
+    const fetchImpl: FetchSpy = vi.fn(async () => xlsxResponse());
+    const ds = makeDS(fetchImpl, 'http://test.local/api/v1');
+
+    await ds.downloadImportTemplate('task');
+
+    expect(new URL(fetchImpl.mock.calls[0][0]).pathname).toBe('/api/v1/data/task/export');
+  });
+
+  it('sends the bearer token like the export does', async () => {
+    const fetchImpl: FetchSpy = vi.fn(async () => xlsxResponse());
+    const ds: any = new ObjectStackAdapter({ baseUrl: 'http://test.local', token: 'tok', fetch: fetchImpl as any });
+    ds.connected = true;
+
+    await ds.downloadImportTemplate('task');
+
+    expect(headerOf(fetchImpl.mock.calls[0][1], 'Authorization')).toBe('Bearer tok');
+  });
+});
+
+describe('ObjectStackAdapter.downloadImportTemplate — same locale as the import request', () => {
+  /**
+   * A fetch that answers both routes: the import's JSON result and the
+   * template's bytes. Every call is recorded, so the two requests are read off
+   * the same spy.
+   */
+  function bothRoutes(): FetchSpy {
+    return vi.fn(async (url: string) =>
+      /\/import(\?|$)/.test(new URL(url).pathname)
+        ? new Response(JSON.stringify({ success: true, data: { total: 0, created: 0, updated: 0, skipped: 0, errors: 0, results: [] } }), {
+            status: 200,
+            headers: { 'Content-Type': 'application/json' },
+          })
+        : xlsxResponse(),
+    );
+  }
+
+  const callTo = (spy: FetchSpy, route: RegExp) => {
+    const call = spy.mock.calls.find(([u]) => route.test(new URL(u).pathname));
+    expect(call, `no request to ${route}`).toBeDefined();
+    return call![1];
+  };
+
+  it('carries the client locale on both requests when one is set', async () => {
+    const fetchImpl = bothRoutes();
+    const ds = makeDS(fetchImpl);
+    ds.getClient().setLocale('zh-CN');
+
+    await ds.importRecords('task', { format: 'json', rows: [] });
+    await ds.downloadImportTemplate('task');
+
+    const importLang = headerOf(callTo(fetchImpl, /\/task\/import$/), 'Accept-Language');
+    const templateLang = headerOf(callTo(fetchImpl, /\/task\/export$/), 'Accept-Language');
+    expect(importLang).toBe('zh-CN');
+    expect(templateLang).toBe(importLang);
+  });
+
+  it('carries none on either when no client locale is set, so the host fetch stamps both alike', async () => {
+    const fetchImpl = bothRoutes();
+    const ds = makeDS(fetchImpl);
+
+    await ds.importRecords('task', { format: 'json', rows: [] });
+    await ds.downloadImportTemplate('task');
+
+    expect(headerOf(callTo(fetchImpl, /\/task\/import$/), 'Accept-Language')).toBeNull();
+    expect(headerOf(callTo(fetchImpl, /\/task\/export$/), 'Accept-Language')).toBeNull();
+  });
+});
+
+describe('ObjectStackAdapter.downloadImportTemplate — refusals', () => {
+  const failWith = (status: number, statusText: string, body: unknown) =>
+    makeDS(
+      vi.fn(
+        async () =>
+          new Response(JSON.stringify(body), {
+            status,
+            statusText,
+            headers: { 'Content-Type': 'application/json' },
+          }),
+      ),
+    );
+
+  it('403: a caller without create gets PERMISSION_DENIED with its sentence', async () => {
+    const ds = failWith(403, 'Forbidden', {
+      success: false,
+      error: {
+        code: 'PERMISSION_DENIED',
+        message: "Creating records on object 'task' is not permitted for this user, so its import template is not served",
+        details: { object: 'task' },
+      },
+    });
+
+    await expect(ds.downloadImportTemplate('task')).rejects.toMatchObject({
+      code: 'PERMISSION_DENIED',
+      status: 403,
+      message: "Creating records on object 'task' is not permitted for this user, so its import template is not served",
+    });
+  });
+
+  it('405: an object not open for import gets OBJECT_API_METHOD_NOT_ALLOWED', async () => {
+    const ds = failWith(405, 'Method Not Allowed', {
+      error: "API operation 'import' is not allowed on object 'task'",
+      code: 'OBJECT_API_METHOD_NOT_ALLOWED',
+      object: 'task',
+      allowed: ['read'],
+    });
+
+    await expect(ds.downloadImportTemplate('task')).rejects.toMatchObject({
+      code: 'OBJECT_API_METHOD_NOT_ALLOWED',
+      status: 405,
+      message: "API operation 'import' is not allowed on object 'task'",
+    });
+  });
+});
@@ -4913,13 +4913,52 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
       }
     }
 
+    return this.fetchExportBlob(resource, queryParams);
+  }
+
+  /**
+   * Download the server's import template:
+   * `GET /api/v1/data/:object/export?template=true` (objectui#9600).
+   *
+   * Same route as {@link exportDownload}, with the server's template switch. It
+   * sends only `template=true`: the server refuses the export's row parameters
+   * on a template request, and its answer is always an xlsx workbook.
+   *
+   * The server writes the template's labels in the request's locale, and the
+   * import accepts a translated label only in its own request's locale. The
+   * import request goes through `@objectstack/client`, which stamps
+   * `Accept-Language` with the client's locale when one is set (and the host's
+   * `fetch` stamps its own otherwise). This request bypasses the client, so it
+   * stamps the client's locale the same way. Both requests then carry the same
+   * locale.
+   */
+  async downloadImportTemplate(resource: string): Promise<Blob> {
+    const locale = this.client.getLocale();
+    return this.fetchExportBlob(
+      resource,
+      new URLSearchParams({ template: 'true' }),
+      locale ? { 'Accept-Language': locale } : undefined,
+    );
+  }
+
+  /**
+   * GET `/api/v1/data/:object/export` with the given query and answer the body
+   * as a Blob. A failure throws an `Error` that carries the server's `status`
+   * and its ADR-0112 `code`. The one request path {@link exportDownload} and
+   * {@link downloadImportTemplate} share.
+   */
+  private async fetchExportBlob(
+    resource: string,
+    queryParams: URLSearchParams,
+    extraHeaders?: Record<string, string>,
+  ): Promise<Blob> {
     const baseUrl = this.baseUrl.replace(/\/$/, '');
     // Avoid doubling /api/v1 if baseUrl already includes the version suffix.
     const hasApiVersionSuffix = /\/api\/v\d+$/i.test(baseUrl);
     const dataPath = hasApiVersionSuffix ? '/data' : '/api/v1/data';
     const url = `${baseUrl}${dataPath}/${encodeURIComponent(resource)}/export?${queryParams.toString()}`;
 
-    const headers: Record<string, string> = { ...this.getAuthHeaders() };
+    const headers: Record<string, string> = { ...this.getAuthHeaders(), ...extraHeaders };
     // `credentials: 'include'` carries the session cookie for the browser
     // console (which authenticates by cookie, not a bearer token).
     const res = await this.fetchImpl(url, { method: 'GET', headers, credentials: 'include' });
 
@@ -566,8 +566,10 @@ const ar = {
     },
     import: {
       downloadTemplate: "تنزيل القالب",
-      downloadTemplateHint: "احصل على ملف CSV بالأعمدة الصحيحة (الحقول المطلوبة معلَّمة بـ *).",
+      downloadTemplateHint: "احصل على ملف Excel بالأعمدة التي يمكنك استيرادها (الحقول المطلوبة معلَّمة بـ *) مع تعليمات التعبئة.",
       templateFileName: "{{object}}-import-template",
+      templateDownloadFailed: "تعذّر تنزيل القالب. يرجى المحاولة مرة أخرى.",
+      templateNotPermitted: "ليست لديك صلاحية إنشاء سجلات لهذا الكائن، لذا فإن قالب الاستيراد غير متاح.",
       autoMatched: "تمت المطابقة تلقائيًا",
       autoMatchedSummary: "تمت مطابقة {{count}} عمودًا تلقائيًا — راجعها وعدّلها أدناه.",
       autoMatchedSummary_zero: "تمت مطابقة {{count}} عمود تلقائيًا — راجِع وعدِّل أدناه.",
 
@@ -502,8 +502,10 @@ const de = {
     },
     import: {
       downloadTemplate: "Vorlage herunterladen",
-      downloadTemplateHint: "Laden Sie eine CSV mit den richtigen Spalten herunter (Pflichtfelder sind mit * markiert).",
+      downloadTemplateHint: "Laden Sie eine Excel-Datei mit den importierbaren Spalten herunter (Pflichtfelder sind mit * markiert), samt Ausfüllhinweisen.",
       templateFileName: "{{object}}-import-template",
+      templateDownloadFailed: "Die Vorlage konnte nicht heruntergeladen werden. Bitte versuchen Sie es erneut.",
+      templateNotPermitted: "Sie sind nicht berechtigt, Datensätze dieses Objekts zu erstellen, daher ist die Importvorlage nicht verfügbar.",
       autoMatched: "Automatisch zugeordnet",
       autoMatchedSummary: "{{count}} Spalte(n) automatisch zugeordnet — unten prüfen und anpassen.",
       autoMatchedSummary_one: "{{count}} Spalte automatisch zugeordnet — unten prüfen und anpassen.",
 
@@ -708,8 +708,10 @@ const en = {
       dragDrop: 'Drag & drop a CSV or Excel file here, or click to browse',
       browseFiles: 'Browse Files',
       downloadTemplate: 'Download template',
-      downloadTemplateHint: 'Get a CSV with the right columns (required fields marked *).',
+      downloadTemplateHint: 'Get an Excel file of the columns you can import (required fields marked *), with instructions for filling it in.',
       templateFileName: '{{object}}-import-template',
+      templateDownloadFailed: 'Could not download the template. Please try again.',
+      templateNotPermitted: 'You do not have permission to create records of this object, so its import template is not available.',
       parsing: 'Parsing…',
       pasteHint: 'or paste (Ctrl/⌘+V) rows copied from Excel or Google Sheets',
       legacyXls: 'Legacy .xls files aren\'t supported — please re-save as .xlsx.',
 
@@ -519,8 +519,10 @@ const es = {
     },
     import: {
       downloadTemplate: "Descargar plantilla",
-      downloadTemplateHint: "Obtenga un CSV con las columnas correctas (los campos obligatorios llevan *).",
+      downloadTemplateHint: "Obtenga un archivo de Excel con las columnas que puede importar (los campos obligatorios llevan *) e instrucciones para rellenarlo.",
       templateFileName: "{{object}}-import-template",
+      templateDownloadFailed: "No se pudo descargar la plantilla. Inténtelo de nuevo.",
+      templateNotPermitted: "No tiene permiso para crear registros de este objeto, por lo que su plantilla de importación no está disponible.",
       autoMatched: "Emparejado automáticamente",
       autoMatchedSummary: "{{count}} columna(s) emparejada(s) automáticamente: revise y ajuste abajo.",
       autoMatchedSummary_one: "{{count}} columna emparejada automáticamente: revise y ajuste abajo.",
 
@@ -515,8 +515,10 @@ const fr = {
     },
     import: {
       downloadTemplate: "Télécharger le modèle",
-      downloadTemplateHint: "Obtenez un CSV avec les bonnes colonnes (les champs obligatoires sont marqués d'un *).",
+      downloadTemplateHint: "Obtenez un fichier Excel des colonnes importables (les champs obligatoires sont marqués d'un *), avec des instructions de saisie.",
       templateFileName: "{{object}}-import-template",
+      templateDownloadFailed: "Impossible de télécharger le modèle. Veuillez réessayer.",
+      templateNotPermitted: "Vous n'êtes pas autorisé à créer des enregistrements de cet objet, son modèle d'import n'est donc pas disponible.",
       autoMatched: "Associé automatiquement",
       autoMatchedSummary: "{{count}} colonne(s) associée(s) automatiquement — vérifiez et ajustez ci-dessous.",
       autoMatchedSummary_one: "{{count}} colonne associée automatiquement — vérifiez et ajustez ci-dessous.",