useDocyrusDataImportWizard

Installation

pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-data-import-wizard

pnpm add @docyrus/app-utils @docyrus/api-client @tanstack/react-query

This hook is distributed as source. It needs an authenticated RestApiClient from @docyrus/api-client and a QueryClientProvider from @tanstack/react-query somewhere above your component tree.

Overview

useDocyrusDataImportWizard is the one-call entry point that wires a Docyrus data source to <DataImportWizard> and returns a ready-to-render wizard element plus an openWizard() trigger. The hook owns:

• Upload — POSTs the picked file to …/import/upload as multipart FormData. RestApiClient auto-detects FormData so no extra headers are needed. Pass uploadFile to replace this phase where the API has no upload route (see Deployments without an upload route).
• Analyse — calls …/import/details?fileName=… to get the parsed columns, sample rows, and unique-field hints.
• Auto-mapping — pre-fills source columns ↔ target fields by scoring slug, name, and token-Jaccard similarity. Required-field slugs and the four reserved slugs (name, description, created_on, autonumber_id) are surfaced in dedicated groups.
• Preview — renders the first N rows using useDocyrusFieldComponent(field.type, 'value-renderer') so every Docyrus field type (relation, money, phone, date, enum, multi-select, …) shows up exactly the way it does in <DataGrid>.
• uniqueData pre-resolution — for enum-like columns the hook resolves matchedId client-side from the field's enum options before posting; relation lookups are left to the server.
• Import — POSTs { fileName, options: { fieldMapping, fieldOptions, uniqueData, upsertUniqueFields } } and returns the result summary (success count, warnings, duplicates, errors) for the wizard's final step.

Backend connection

The hook calls three endpoints on the Docyrus API by default. You can override any of them via endpoints:

Deployments without an upload route

The upload row above is a contract, not a guarantee: an API can ship the analyse and import routes without an upload route. There the raw file is expected to already sit in tenant storage at tenant-{tenantNo}/tmp/import/{fileName}, and the analyse phase rebuilds that path from the tenant in the caller's token plus the fileName you hand it.

Put the file there yourself and pass uploadFile; analyse and import stay untouched:

const { openWizard, wizard } = useDocyrusDataImportWizard({
  client,
  appSlug,
  dataSourceSlug,
  fields: dataSource?.fields,
  uploadFile: async (file) => {
    const fileName = /* slugified base + original extension */;

    await putIntoTenantStorage(`tenant-${tenantNo}/tmp/import/${fileName}`, file);

    return { fileName, originalName: file.name, size: file.size, mimeType: file.type };
  },
  onImported: reload,
});

Two things have to line up or analyse will not find the file: the fileName you return must be the last segment of the path you wrote to, and the tenant in the path must be the tenant the analyse call authenticates as.

Required fields are sourced from one of:

1. fields option — pass the same DataSourceField[] you already use with useDocyrusDataGrid to skip an extra round-trip.
2. Auto-load — when fields is omitted the hook composes useDocyrusDataViewSelect under the hood and reads dataSource.fields.

Usage

'use client';

import { useDocyrusAuth } from '@docyrus/signin';

import { Button } from '@docyrus/ui/primitives/ui/button';
import { useDocyrusDataImportWizard } from '@docyrus/ui/library/hooks/use-docyrus-data-import-wizard';

export function ContactsToolbar({ onImported }: { onImported: () => void }) {
  const { client } = useDocyrusAuth();

  if (!client) return null;

  const { openWizard, wizard } = useDocyrusDataImportWizard({
    client,
    appSlug: 'crm',
    dataSourceSlug: 'contact',
    requiredFieldSlugs: ['email'],
    onImported: () => onImported()
  });

  return (
    <>
      <Button onClick={openWizard}>Import contacts…</Button>
      {wizard}
    </>
  );
}

Side-by-side with useDocyrusDataGrid

Both hooks accept the same client + appSlug + dataSourceSlug. Wire onImported to the grid's reload() so a successful import refreshes the visible rows:

const grid = useDocyrusDataGrid({ client, appSlug, dataSourceSlug });
const importer = useDocyrusDataImportWizard({
  client,
  appSlug,
  dataSourceSlug,
  fields: grid.fields,                 // skip duplicate metadata fetch
  onImported: () => grid.reload()
});

return (
  <>
    {grid.toolbar}
    <DataGrid table={grid.table} {...grid.gridProps} />
    <Button onClick={importer.openWizard}>Import…</Button>
    {importer.wizard}
  </>
);

Imperative usage (skip the dialog UI)

const importer = useDocyrusDataImportWizard({ client, appSlug, dataSourceSlug });

async function silentImport(file: File) {
  const uploaded = await importer.uploadAsync(file);
  await importer.analyseAsync(uploaded.fileName);
  // …mutate `importer.mapping` via your own UI…
  return importer.importAsync();
}

API Reference

Parameters

Return Value

Field-Type Awareness

The wizard uses field metadata in three places:

Error Handling

• File-too-large, wrong-extension, and empty-file errors fire client-side and surface as inline banners on the upload step (no network round-trip).
• Network errors are stored on each mutation's error and shown in the same banner; onError(err, phase) fires for telemetry.
• Partial server-side errors come back in importResult.error[] — rendered as a per-row error list on the result step.
• The wizard locks the close button (preventOutsideClose) while any phase is in flight so the user can't accidentally drop the upload mid-stream.