Skip to content

export.mdx

Latest commit

 

History

History
596 lines (412 loc) · 24.5 KB

export.mdx

File metadata and controls

596 lines (412 loc) · 24.5 KB
Raw
title Export
description Export protocol schemas

{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}

Data Export & Import Protocol

Defines schemas for streaming data export, import validation,

template-based field mapping, and scheduled export jobs.

Industry alignment: Salesforce Data Export, Airtable CSV Export,

Dynamics 365 Data Management.

Base path: /api/v1/data/{object}/export

**Source:** `packages/spec/src/api/export.zod.ts`

TypeScript Usage

import { CreateExportJobRequest, CreateExportJobResponse, CreateImportJobRequest, CreateImportJobResponse, DeduplicationStrategy, ExportFormat, ExportImportTemplate, ExportJobProgress, ExportJobStatus, ExportJobSummary, FieldMappingEntry, GetExportJobDownloadRequest, GetExportJobDownloadResponse, ImportJobProgress, ImportJobResults, ImportJobStatus, ImportJobSummary, ImportMapping, ImportRequest, ImportResponse, ImportRowResult, ImportValidationConfig, ImportValidationMode, ImportValidationResult, ImportWriteMode, ListExportJobsRequest, ListExportJobsResponse, ListImportJobsRequest, ListImportJobsResponse, ScheduleExportRequest, ScheduleExportResponse, ScheduledExport, UndoImportJobResponse } from '@objectstack/spec/api';
import type { CreateExportJobRequest, CreateExportJobResponse, CreateImportJobRequest, CreateImportJobResponse, DeduplicationStrategy, ExportFormat, ExportImportTemplate, ExportJobProgress, ExportJobStatus, ExportJobSummary, FieldMappingEntry, GetExportJobDownloadRequest, GetExportJobDownloadResponse, ImportJobProgress, ImportJobResults, ImportJobStatus, ImportJobSummary, ImportMapping, ImportRequest, ImportResponse, ImportRowResult, ImportValidationConfig, ImportValidationMode, ImportValidationResult, ImportWriteMode, ListExportJobsRequest, ListExportJobsResponse, ListImportJobsRequest, ListImportJobsResponse, ScheduleExportRequest, ScheduleExportResponse, ScheduledExport, UndoImportJobResponse } from '@objectstack/spec/api';

// Validate data
const result = CreateExportJobRequest.parse(data);

CreateExportJobRequest

Properties

Property Type Required Description
object string ✅ Object name to export
format Enum<'csv' | 'json' | 'jsonl' | 'xlsx' | 'parquet'> ✅ Export file format
fields string[] optional Specific fields to include (omit for all fields)
filter Record<string, any> optional Filter criteria for records to export
sort { field: string; direction: Enum<'asc' | 'desc'> }[] optional Sort order for exported records
limit integer optional Maximum number of records to export
includeHeaders boolean ✅ Include header row (CSV/XLSX)
encoding string ✅ Character encoding for the export file
templateId string optional Export template ID for predefined field mappings

CreateExportJobResponse

Properties

Property Type Required Description
success boolean ✅ Operation success status
error { code: string; message: string; category?: string; details?: any; … } optional Error details if success is false
meta { timestamp: string; duration?: number; requestId?: string; traceId?: string } optional Response metadata
data { jobId: string; status: Enum<'pending' | 'processing' | 'completed' | 'failed' | 'cancelled' | 'expired'>; estimatedRecords?: integer; createdAt: string } ✅

CreateImportJobRequest

Properties

Property Type Required Description
format Enum<'csv' | 'json' | 'xlsx'> optional Payload shape: csv text, a rows[] array, or a base64 xlsx (inferred when omitted)
csv string optional CSV text (when format = csv)
rows Record<string, any>[] optional Row objects (when format = json)
xlsxBase64 string optional Base64-encoded .xlsx workbook bytes (when format = xlsx); parsed server-side
sheet string | integer optional Worksheet name or 1-based index to read (xlsx; defaults to the first sheet)
mapping Record<string, string> | { sourceField: string; targetField: string; targetLabel?: string; transform: Enum<'none' | 'uppercase' | 'lowercase' | 'trim' | 'date_format' | 'lookup'>; … }[] optional Source column → target field mapping
dryRun boolean ✅ Validate + coerce every row without persisting
writeMode Enum<'insert' | 'update' | 'upsert'> ✅ insert / update / upsert semantics
matchFields string[] optional Fields that identify an existing record (required for update/upsert)
runAutomations boolean ✅ Fire triggers/hooks for each imported row (off by default for bulk)
trimWhitespace boolean ✅ Trim leading/trailing whitespace from string cells
nullValues string[] optional Strings treated as null/blank (besides empty string)
createMissingOptions boolean ✅ Keep unmatched select values instead of failing the row
skipBlankMatchKey boolean ✅ Skip rows whose matchFields are blank (default: upsert creates them, update skips them)

CreateImportJobResponse

Properties

Property Type Required Description
jobId string ✅ Import job id — poll progress/results with this
object string ✅ Target object name
status Enum<'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled'> ✅ Initial job status (usually "pending")
total integer ✅ Rows accepted for processing
createdAt string ✅ Job creation timestamp (ISO 8601)

DeduplicationStrategy

Allowed Values

  • skip
  • update
  • create_new
  • fail

ExportFormat

Allowed Values

  • csv
  • json
  • jsonl
  • xlsx
  • parquet

ExportImportTemplate

Properties

Property Type Required Description
id string optional Template ID (generated on save)
name string ✅ Template machine name (snake_case)
label string ✅ Human-readable template label
description string optional Template description
object string ✅ Target object name
direction Enum<'import' | 'export' | 'bidirectional'> ✅ Template direction
format Enum<'csv' | 'json' | 'jsonl' | 'xlsx' | 'parquet'> optional Default file format for this template
mappings { sourceField: string; targetField: string; targetLabel?: string; transform: Enum<'none' | 'uppercase' | 'lowercase' | 'trim' | 'date_format' | 'lookup'>; … }[] ✅ Field mapping entries
createdAt string optional Template creation timestamp
updatedAt string optional Last update timestamp
createdBy string optional User who created the template

ExportJobProgress

Properties

Property Type Required Description
success boolean ✅ Operation success status
error { code: string; message: string; category?: string; details?: any; … } optional Error details if success is false
meta { timestamp: string; duration?: number; requestId?: string; traceId?: string } optional Response metadata
data { jobId: string; status: Enum<'pending' | 'processing' | 'completed' | 'failed' | 'cancelled' | 'expired'>; format: Enum<'csv' | 'json' | 'jsonl' | 'xlsx' | 'parquet'>; totalRecords?: integer; … } ✅

ExportJobStatus

Allowed Values

  • pending
  • processing
  • completed
  • failed
  • cancelled
  • expired

ExportJobSummary

Properties

Property Type Required Description
jobId string ✅ Export job ID
object string ✅ Object name that was exported
status Enum<'pending' | 'processing' | 'completed' | 'failed' | 'cancelled' | 'expired'> ✅ Current job status
format Enum<'csv' | 'json' | 'jsonl' | 'xlsx' | 'parquet'> ✅ Export file format
totalRecords integer optional Total records exported
fileSize integer optional File size in bytes
createdAt string ✅ Job creation timestamp
completedAt string optional Completion timestamp
createdBy string optional User who initiated the export

FieldMappingEntry

Properties

Property Type Required Description
sourceField string ✅ Field name in the source data (import) or object (export)
targetField string ✅ Field name in the target object (import) or file column (export)
targetLabel string optional Display label for the target column (export)
transform Enum<'none' | 'uppercase' | 'lowercase' | 'trim' | 'date_format' | 'lookup'> ✅ Transformation to apply during mapping
defaultValue any optional Default value if source field is null/empty
required boolean ✅ Whether this field is required (import validation)

GetExportJobDownloadRequest

Properties

Property Type Required Description
jobId string ✅ Export job ID

GetExportJobDownloadResponse

Properties

Property Type Required Description
success boolean ✅ Operation success status
error { code: string; message: string; category?: string; details?: any; … } optional Error details if success is false
meta { timestamp: string; duration?: number; requestId?: string; traceId?: string } optional Response metadata
data { jobId: string; downloadUrl: string; fileName: string; fileSize: integer; … } ✅

ImportJobProgress

Properties

Property Type Required Description
jobId string ✅ Import job id
object string ✅ Target object name
status Enum<'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled'> ✅ Current job status
dryRun boolean ✅ Whether this is a validate-only pass
writeMode Enum<'insert' | 'update' | 'upsert'> ✅ Write mode used
total integer ✅ Total rows to process
processed integer ✅ Rows processed so far
created integer ✅ Rows that created a new record
updated integer ✅ Rows that updated an existing record
skipped integer ✅ Rows skipped
errors integer ✅ Rows that failed
percentComplete number ✅ processed / total as a percentage
undoable boolean ✅ Whether this job can still be logically rolled back (undo log captured, terminal state, not yet reverted)
revertedAt string optional When the job was undone / rolled back (ISO 8601)
error string optional Fatal error message (when status = failed)
startedAt string optional Processing start timestamp (ISO 8601)
completedAt string optional Completion timestamp (ISO 8601)
createdAt string ✅ Job creation timestamp (ISO 8601)

ImportJobResults

Properties

Property Type Required Description
jobId string ✅ Import job id
object string ✅ Target object name
status Enum<'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled'> ✅ Current job status
dryRun boolean ✅ Whether this is a validate-only pass
writeMode Enum<'insert' | 'update' | 'upsert'> ✅ Write mode used
total integer ✅ Total rows to process
processed integer ✅ Rows processed so far
created integer ✅ Rows that created a new record
updated integer ✅ Rows that updated an existing record
skipped integer ✅ Rows skipped
errors integer ✅ Rows that failed
percentComplete number ✅ processed / total as a percentage
undoable boolean ✅ Whether this job can still be logically rolled back (undo log captured, terminal state, not yet reverted)
revertedAt string optional When the job was undone / rolled back (ISO 8601)
error string optional Fatal error message (when status = failed)
startedAt string optional Processing start timestamp (ISO 8601)
completedAt string optional Completion timestamp (ISO 8601)
createdAt string ✅ Job creation timestamp (ISO 8601)
results { row: integer; ok: boolean; action: Enum<'created' | 'updated' | 'skipped' | 'failed'>; id?: string; … }[] ✅ Capped sample of per-row outcomes (failures first)
resultsTruncated boolean ✅ Whether results is a capped sample of a larger set

ImportJobStatus

Allowed Values

  • pending
  • running
  • succeeded
  • failed
  • cancelled

ImportJobSummary

Properties

Property Type Required Description
jobId string ✅ Import job id
object string ✅ Target object name
status Enum<'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled'> ✅ Job status
total integer ✅ Total rows
processed integer ✅ Rows processed
created integer ✅ Rows created
updated integer ✅ Rows updated
skipped integer ✅ Rows skipped
errors integer ✅ Rows failed
createdAt string ✅ Job creation timestamp (ISO 8601)
completedAt string optional Completion timestamp (ISO 8601)
undoable boolean ✅ Whether this job can still be logically rolled back
revertedAt string optional When the job was undone / rolled back (ISO 8601)

ImportMapping

Union Options

This schema accepts one of the following structures:

Option 1

Type: Record<string, string>

Option 2

Type: { sourceField: string; targetField: string; targetLabel?: string; transform: Enum<'none' | 'uppercase' | 'lowercase' | 'trim' | 'date_format' | 'lookup'>; … }[]

ImportRequest

Properties

Property Type Required Description
format Enum<'csv' | 'json' | 'xlsx'> optional Payload shape: csv text, a rows[] array, or a base64 xlsx (inferred when omitted)
csv string optional CSV text (when format = csv)
rows Record<string, any>[] optional Row objects (when format = json)
xlsxBase64 string optional Base64-encoded .xlsx workbook bytes (when format = xlsx); parsed server-side
sheet string | integer optional Worksheet name or 1-based index to read (xlsx; defaults to the first sheet)
mapping Record<string, string> | { sourceField: string; targetField: string; targetLabel?: string; transform: Enum<'none' | 'uppercase' | 'lowercase' | 'trim' | 'date_format' | 'lookup'>; … }[] optional Source column → target field mapping
dryRun boolean ✅ Validate + coerce every row without persisting
writeMode Enum<'insert' | 'update' | 'upsert'> ✅ insert / update / upsert semantics
matchFields string[] optional Fields that identify an existing record (required for update/upsert)
runAutomations boolean ✅ Fire triggers/hooks for each imported row (off by default for bulk)
trimWhitespace boolean ✅ Trim leading/trailing whitespace from string cells
nullValues string[] optional Strings treated as null/blank (besides empty string)
createMissingOptions boolean ✅ Keep unmatched select values instead of failing the row
skipBlankMatchKey boolean ✅ Skip rows whose matchFields are blank (default: upsert creates them, update skips them)

ImportResponse

Properties

Property Type Required Description
object string ✅ Target object name
dryRun boolean ✅ Whether this was a validate-only pass
writeMode Enum<'insert' | 'update' | 'upsert'> ✅ Write mode used
total integer ✅ Rows processed
ok integer ✅ Rows that succeeded
errors integer ✅ Rows that failed
created integer ✅ Rows that created a new record
updated integer ✅ Rows that updated an existing record
skipped integer ✅ Rows skipped (no match in update mode, etc.)
results { row: integer; ok: boolean; action: Enum<'created' | 'updated' | 'skipped' | 'failed'>; id?: string; … }[] ✅ Per-row outcomes

ImportRowResult

Properties

Property Type Required Description
row integer ✅ 1-based row number in the source data
ok boolean ✅ Whether the row succeeded
action Enum<'created' | 'updated' | 'skipped' | 'failed'> ✅ What happened to the row
id string optional Record id (created/updated rows)
field string optional Field that caused a coercion/validation error
code string optional Error code (failed rows)
error string optional Human-readable error message (failed rows)

ImportValidationConfig

Properties

Property Type Required Description
mode Enum<'strict' | 'lenient' | 'dry_run'> ✅ Validation mode for the import
deduplication { strategy: Enum<'skip' | 'update' | 'create_new' | 'fail'>; matchFields: string[] } optional Deduplication configuration
maxErrors integer ✅ Maximum validation errors before aborting
trimWhitespace boolean ✅ Trim leading/trailing whitespace from string fields
dateFormat string optional Expected date format in import data (e.g., "YYYY-MM-DD")
nullValues string[] optional Strings to treat as null (e.g., ["", "N/A", "null"])

ImportValidationMode

Allowed Values

  • strict
  • lenient
  • dry_run

ImportValidationResult

Properties

Property Type Required Description
success boolean ✅ Operation success status
error { code: string; message: string; category?: string; details?: any; … } optional Error details if success is false
meta { timestamp: string; duration?: number; requestId?: string; traceId?: string } optional Response metadata
data { totalRecords: integer; validRecords: integer; invalidRecords: integer; duplicateRecords: integer; … } ✅

ImportWriteMode

Allowed Values

  • insert
  • update
  • upsert

ListExportJobsRequest

Properties

Property Type Required Description
object string optional Filter by object name
status Enum<'pending' | 'processing' | 'completed' | 'failed' | 'cancelled' | 'expired'> optional Filter by job status
limit integer ✅ Maximum number of jobs to return
cursor string optional Pagination cursor from a previous response

ListExportJobsResponse

Properties

Property Type Required Description
success boolean ✅ Operation success status
error { code: string; message: string; category?: string; details?: any; … } optional Error details if success is false
meta { timestamp: string; duration?: number; requestId?: string; traceId?: string } optional Response metadata
data { jobs: { jobId: string; object: string; status: Enum<'pending' | 'processing' | 'completed' | 'failed' | 'cancelled' | 'expired'>; format: Enum<'csv' | 'json' | 'jsonl' | 'xlsx' | 'parquet'>; … }[]; nextCursor?: string; hasMore: boolean } ✅

ListImportJobsRequest

Properties

Property Type Required Description
object string optional Filter to one target object
status Enum<'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled'> optional Filter by job status
limit integer ✅ Max rows to return
offset integer ✅ Pagination offset

ListImportJobsResponse

Properties

Property Type Required Description
jobs { jobId: string; object: string; status: Enum<'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled'>; total: integer; … }[] ✅ Import jobs, newest first

ScheduleExportRequest

Properties

Property Type Required Description
name string ✅ Schedule name (snake_case)
label string optional Human-readable label
object string ✅ Object name to export
format Enum<'csv' | 'json' | 'jsonl' | 'xlsx' | 'parquet'> optional Export file format
fields string[] optional Fields to include
filter Record<string, any> optional Record filter criteria
templateId string optional Export template ID for field mappings
schedule { cronExpression: string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object }; timezone?: string } ✅ Schedule timing configuration
delivery { method: Enum<'email' | 'storage' | 'webhook'>; recipients?: string[]; storagePath?: string; webhookUrl?: string } ✅ Export delivery configuration

ScheduleExportResponse

Properties

Property Type Required Description
success boolean ✅ Operation success status
error { code: string; message: string; category?: string; details?: any; … } optional Error details if success is false
meta { timestamp: string; duration?: number; requestId?: string; traceId?: string } optional Response metadata
data { id: string; name: string; enabled: boolean; nextRunAt?: string; … } ✅

ScheduledExport

Properties

Property Type Required Description
id string optional Scheduled export ID
name string ✅ Schedule name (snake_case)
label string optional Human-readable label
object string ✅ Object name to export
format Enum<'csv' | 'json' | 'jsonl' | 'xlsx' | 'parquet'> optional Export file format
fields string[] optional Fields to include
filter Record<string, any> optional Record filter criteria
templateId string optional Export template ID for field mappings
schedule { cronExpression: string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object }; timezone?: string } ✅ Schedule timing configuration
delivery { method: Enum<'email' | 'storage' | 'webhook'>; recipients?: string[]; storagePath?: string; webhookUrl?: string } ✅ Export delivery configuration
enabled boolean optional Whether the scheduled export is active
lastRunAt string optional Last execution timestamp
nextRunAt string optional Next scheduled execution
createdAt string optional Creation timestamp
createdBy string optional User who created the schedule

UndoImportJobResponse

Properties

Property Type Required Description
success boolean ✅ Whether the undo completed
jobId string ✅ Import job id
object string ✅ Target object name
deleted integer ✅ Created records deleted
restored integer ✅ Updated records restored to pre-import values
failed integer ✅ Reversal operations that failed