useDocyrusDataImportWizard

Installation

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

pnpm add @docyrus/api-client @docyrus/app-utils @tanstack/react-query expo-document-picker (optional)

This is a port of the web hook with the same options and result. It needs an authenticated RestApiClient and a QueryClientProvider above it. The file is picked with the optional expo-document-picker peer and parsed on the server, so no spreadsheet library runs on the device. The hook renders DataImportWizard.

How it works

1. Fields. Target fields come from useDocyrusDataSourceFields while the wizard is open (cache-first through the shared inventory), unless you pass fields.
2. Upload. Picking a file POSTs multipart FormData with a React Native file part ({ uri, name, type }) to …/import/upload. RestApiClient detects FormData and leaves the Content-Type to fetch. Pass uploadFile to replace this phase.
3. Analyse. GET …/import/details?fileName=… returns the columns, rows (data is normalized to rows) and unique-field hints. The mapping is seeded from initialMapping or buildAutoMapping(columns, fields). If the fields load after the analysis, auto-mapping runs again.
4. Import. Enum-like columns are resolved to option ids on the device and sent as uniqueData. Relation lookups are left to the server. The hook POSTs { fileName, options } to …/import, where options comes from buildImportOptions(mapping, fields, upsertUniqueFields, uniqueData).

All three endpoints default to /v1/apps/{appSlug}/data-sources/{dataSourceSlug}/import/… and can be overridden with endpoints. Closing the wizard resets the run, so the next open starts fresh.

Deployments without an upload route

When the API has no POST …/import/upload, the raw file must already be in tenant storage under tenant-{tenantNo}/tmp/import/{fileName}. Pass uploadFile to put it there yourself and return the UploadedFileInfo. The returned fileName is what the analyse and import phases use.

Usage

import { useDocyrusClient } from '@docyrus/signin/react-native';

import { Button } from '@/components/docyrus-native/button';
import { useDocyrusDataImportWizard } from '@/hooks/docyrus-native/use-docyrus-data-import-wizard';

export function ImportContacts({ onDone }: { onDone: () => void }) {
  const client = useDocyrusClient();
  const { wizard, openWizard, isImporting } = useDocyrusDataImportWizard({
    client: client!,
    appSlug: 'base',
    dataSourceSlug: 'contact',
    requiredFieldSlugs: ['name'],
    onImported: () => onDone(),
    onError: (error, phase) => console.warn(phase, error.message)
  });

  return (
    <>
      <Button onPress={openWizard} disabled={isImporting}>Import</Button>
      {wizard}
    </>
  );
}

Imperative usage

uploadAsync and analyseAsync call the endpoints directly and resolve their responses without changing the wizard state. They are useful for custom flows and tests. importAsync imports the file the wizard has already analysed, using the current mapping. It throws when no file has been analysed yet, and it skips the on-device uniqueData pre-resolution.

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

const uploaded = await importer.uploadAsync(file); // DataImportFile
const analysed = await importer.analyseAsync(uploaded.fileName);

// …after the user went through the mapping step:
const result = await importer.importAsync();

API Reference

Options (UseDocyrusDataImportWizardOptions)

Result (UseDocyrusDataImportWizardResult)

Differences from web

• File becomes DataImportFile (NativeFile: { uri, name, type, size? }), and the upload sends a React Native FormData file part.
• Target fields come from the lightweight useDocyrusDataSourceFields schema hook instead of useDocyrusDataViewSelect.
• The wizard is a full-height bottom sheet, and the file comes from the system document picker instead of drag-and-drop.

Type Exports

The wizard types (DataImportFile, ImportWizardStep, WizardMappingMap, UploadedFileInfo, AnalysedFile, ImportResultPayload, …) are exported from data-import-wizard.