MaintainX Data Handling
Overview
Patterns for synchronizing, transforming, and exporting data between MaintainX and external systems (databases, data warehouses, ERPs).
Prerequisites
- MaintainX API access configured
- Node.js 18+ with
axios
- Target database or data warehouse available
Instructions
Step 1: Incremental Sync with Cursor Pagination
import { MaintainXClient } from './client';
import { writeFileSync, existsSync, readFileSync } from 'fs';
const SYNC_STATE_FILE = '.maintainx-sync-state.json';
interface SyncState {
lastSyncAt: string;
workOrderCursor?: string;
assetCursor?: string;
}
function loadSyncState(): SyncState {
if (existsSync(SYNC_STATE_FILE)) {
return JSON.parse(readFileSync(SYNC_STATE_FILE, 'utf-8'));
}
return { lastSyncAt: new Date(0).toISOString() };
}
function saveSyncState(state: SyncState) {
writeFileSync(SYNC_STATE_FILE, JSON.stringify(state, null, 2));
}
async function incrementalSync(client: MaintainXClient) {
const state = loadSyncState();
const syncStart = new Date().toISOString();
console.log(`Syncing changes since ${state.lastSyncAt}`);
let cursor: string | undefined;
let totalWOs = 0;
do {
const response = await client.getWorkOrders({
updatedAtGte: state.lastSyncAt,
limit: 100,
cursor,
});
for (const wo of response.workOrders) {
await upsertWorkOrder(wo);
totalWOs++;
}
cursor = response.cursor ?? undefined;
} while (cursor);
let assetCursor: string | undefined;
let totalAssets = 0;
do {
const response = await client.getAssets({
updatedAtGte: state.lastSyncAt,
limit: 100,
cursor: assetCursor,
});
for (const asset of response.assets) {
await upsertAsset(asset);
totalAssets++;
}
assetCursor = response.cursor ?? undefined;
} while (assetCursor);
saveSyncState({ lastSyncAt: syncStart });
console.log(`Synced ${totalWOs} work orders, ${totalAssets} assets`);
}
Step 2: Export to CSV
import { createWriteStream } from 'fs';
async function exportWorkOrdersToCSV(client: MaintainXClient, outputPath: string) {
const stream = createWriteStream(outputPath);
stream.write('id,title,status,priority,assignee,asset,location,created_at,completed_at\n');
let cursor: string | undefined;
let count = 0;
do {
const response = await client.getWorkOrders({ limit: 100, cursor });
for (const wo of response.workOrders) {
const row = [
wo.id,
`"${(wo.title || '').replace(/"/g, '""')}"`,
wo.status,
wo.priority,
wo.assignees?.map((a: any) => a.id).join(';') || '',
wo.assetId || '',
wo.locationId || '',
wo.createdAt,
wo.completedAt || '',
].join(',');
stream.write(row + '\n');
count++;
}
cursor = response.cursor ?? undefined;
} while (cursor);
stream.end();
console.log(`Exported ${count} work orders to ${outputPath}`);
}
// Usage
await exportWorkOrdersToCSV(client, 'work-orders-export.csv');
Step 3: Export to BigQuery
import { BigQuery } from '@google-cloud/bigquery';
const bq = new BigQuery({ projectId: 'your-project' });
const dataset = bq.dataset('maintenance');
const table = dataset.table('work_orders');
async function syncToBigQuery(client: MaintainXClient) {
let cursor: string | undefined;
const batch: any[] = [];
do {
const response = await client.getWorkOrders({ limit: 100, cursor });
for (const wo of response.workOrders) {
batch.push({
id: wo.id,
title: wo.title,
status: wo.status,
priority: wo.priority,
asset_id: wo.assetId,
location_id: wo.locationId,
created_at: wo.,
: wo.,
: ().(),
});
}
cursor = response. ?? ;
} (cursor);
(batch. > ) {
table.(batch);
.();
}
}
Step 4: Data Reconciliation
async function reconcile(client: MaintainXClient, localDb: any) {
const remoteOrders = await paginate(
(cursor) => client.getWorkOrders({ limit: 100, cursor }),
'workOrders',
);
const localOrders = await localDb.query('SELECT id, updated_at FROM work_orders');
const remoteMap = new Map(remoteOrders.map((wo: any) => [wo.id, wo.updatedAt]));
const localMap = new Map(localOrders.map((row: any) => [row.id, row.updated_at]));
const missing = remoteOrders.filter((wo: any) => !localMap.has(wo.id));
const stale = remoteOrders.filter(
(wo: ) => localMap.(wo.) && localMap.(wo.) < remoteMap.(wo.),
);
orphaned = localOrders.( !remoteMap.(row.));
.();
.();
.();
{ missing, stale, orphaned };
}
Output
- Incremental sync with persistent cursor state
- CSV export of work orders with proper quoting
- BigQuery streaming insert pipeline
- Data reconciliation report (missing, stale, orphaned records)
Error Handling
| Issue | Cause | Solution |
|---|
| 429 Rate Limited | Too many requests during sync | Add delays between pages, use p-queue |
| Partial sync failure | Network error mid-pagination | Save cursor state, resume from last position |
| Duplicate rows in BigQuery | Re-running without dedup | Use MERGE or dedup on (id, updated_at) |
| Stale local data | Missed webhook or sync gap | Run full reconciliation, then incremental |
Resources
Next Steps
For enterprise access control, see maintainx-enterprise-rbac.
Examples
Scheduled sync with cron:
import cron from 'node-cron';
cron.schedule('*/15 * * * *', async () => {
console.log('Starting incremental sync...');
await incrementalSync(new MaintainXClient());
});
Import work orders from a legacy CMMS CSV:
import { parse } from 'csv-parse/sync';
import { readFileSync } from 'fs';
const rows = parse(readFileSync('legacy-export.csv'), { columns: true });
for (const row of rows) {
await client.createWorkOrder({
title: row['Work Order Name'],
description: row['Description'],
priority: row['Priority'].toUpperCase(),
categories: [row['Type'].toUpperCase()],
});
}
