MaintainX Cost Tuning

Overview

Reduce MaintainX API request volume and optimize costs through caching, webhook-driven sync, request batching, and smart polling strategies.

Prerequisites

• MaintainX integration deployed and working
• Redis or in-memory cache available
• Baseline API usage metrics

Instructions

Step 1: Request Volume Tracking

// src/cost/usage-tracker.ts

class ApiUsageTracker {
  private counts: Map<string, number> = new Map();
  private startTime = Date.now();

  record(endpoint: string) {
    const key = endpoint.split('?')[0]; // Strip query params
    this.counts.set(key, (this.counts.get(key) || 0) + 1);
  }

  report() {
    const elapsed = (Date.now() - this.startTime) / 1000 / 60; // minutes
    console.log(`\n=== API Usage Report (${elapsed.toFixed(1)} min) ===`);
    const sorted = [...this.counts.entries()].sort((a, b) => b[1] - a[1]);
    for (const [endpoint, count] of sorted) {
      const rate = (count / elapsed).toFixed(1);
      console.log(`  ${endpoint}: ${count} calls (${rate}/min)`);
    }
    console.log(`  TOTAL: ${[...this.counts.values()].reduce((a, b) => a + b, 0)} calls`);
  }
}

export const tracker = new ApiUsageTracker();
// Report every 10 minutes
setInterval(() => tracker.report(), 600_000);

Step 2: Response Caching

// src/cost/cached-client.ts

interface CacheEntry<T> {
  data: T;
  expiresAt: number;
}

class CachedMaintainXClient {
  private cache = new Map<string, CacheEntry<any>>();
  private client: MaintainXClient;

  // TTL per resource type (in seconds)
  private ttl: Record<string, number> = {
    '/users': 300,       // 5 min - users rarely change
    '/locations': 300,   // 5 min - locations are static
    '/assets': 120,      // 2 min - assets change infrequently
    '/workorders': 30,   // 30 sec - work orders change often
    '/teams': 600,       // 10 min - teams are very static
  };

  constructor(client: MaintainXClient) {
    this.client = client;
  }

  async get<T>(endpoint: string, params?: any): Promise<T> {
    const cacheKey = `${endpoint}:${JSON.stringify(params || {})}`;
    const cached = this.cache.get(cacheKey);

    if (cached && cached.expiresAt > Date.now()) {
      console.log(`[CACHE HIT] ${endpoint}`);
      return cached.data;
    }

    const basePath = '/' + endpoint.split('/').filter(Boolean)[0];
    const ttlSec = this.ttl[basePath] || 60;

    const data = await this.client.request('GET', endpoint, undefined, params);
    this.cache.set(cacheKey, {
      data,
      expiresAt: Date.now() + ttlSec * 1000,
    });

    tracker.record(endpoint);
    return data as T;
  }

  invalidate(pattern: string) {
    for (const key of this.cache.keys()) {
      if (k

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}`);

  // Sync work orders updated since last run
  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);  // Your DB write function
      totalWOs++;
    }
    cursor = response.cursor ?? undefined;
  } while (cursor);

  // Sync assets updated since last run
  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);  // Your DB write function
      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.assig

MaintainX Debug Bundle

Current State

!node --version 2>/dev/null || echo 'N/A'

!python3 --version 2>/dev/null || echo 'N/A'

!echo "API key set: $([ -n "$MAINTAINXAPIKEY" ] && echo 'yes' || echo 'no')"

Overview

Complete debugging toolkit for diagnosing and resolving MaintainX integration issues with diagnostic scripts, request logging, and health checks.

Prerequisites

• MaintainX API access configured
• Node.js 18+ or curl
• MAINTAINXAPIKEY environment variable set

Instructions

Step 1: Environment Diagnostic Script

#!/bin/bash
echo "=== MaintainX Debug Report ==="
echo "Timestamp: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
echo "Node.js: $(node --version 2>/dev/null || echo 'not installed')"
echo "npm: $(npm --version 2>/dev/null || echo 'not installed')"
echo "API key set: $([ -n "$MAINTAINX_API_KEY" ] && echo 'yes (length: '${#MAINTAINX_API_KEY}')' || echo 'NO')"
echo ""

echo "=== API Connectivity ==="
HTTP_CODE=$(curl -s -o /tmp/mx-debug.json -w "%{http_code}" \
  "https://api.getmaintainx.com/v1/users?limit=1" \
  -H "Authorization: Bearer $MAINTAINX_API_KEY")
echo "Auth status: $HTTP_CODE"

if [ "$HTTP_CODE" = "200" ]; then
  echo "Response: $(cat /tmp/mx-debug.json | jq -c '{users: (.users | length)}')"
else
  echo "Error: $(cat /tmp/mx-debug.json | jq -r '.message // .error // "unknown"')"
fi

echo ""
echo "=== DNS Resolution ==="
nslookup api.getmaintainx.com 2>/dev/null | grep -A1 "Name:"

echo ""
echo "=== Response Timing ==="
curl -s -o /dev/null -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTTFB: %{time_starttransfer}s\nTotal: %{time_total}s\n" \
  "https://api.getmaintainx.com/v1/users?limit=1" \
  -H "Authorization: Bearer $MAINTAINX_API_KEY"

Step 2: Request/Response Logger

// src/debug/request-logger.ts
import axios, { AxiosInstance, AxiosError } from 'axios';

export function createDebugClient(): AxiosInstance {
  const client = axios.create({
    baseURL: 'https://api.getmaintainx.com/v1',
    headers: {
      Authorization: `Bearer ${process.env.MAINTAINX_API_KEY}`,
      'Content-Type': 'application/json',
    },
  });

  // Request interceptor
  client.interceptors.request.use((config) => {
    const startTime = Date.now();
    (config as any).__startTime = startTime;
    console.log(`[REQ] ${config.method?.toUpperCase()} ${config.url}`);
    if (config.data) console.log('  Body:', JSON.stringify(confi

MaintainX Deploy Integration

Overview

Deploy MaintainX integrations to production using Docker, Google Cloud Run, and Kubernetes with proper health checks and secret management.

Prerequisites

• MaintainX integration tested and passing CI
• Docker installed
• Cloud platform account (GCP recommended)
• MAINTAINXAPIKEY for production environment

Instructions

Step 1: Dockerfile

# Dockerfile
FROM node:20-slim AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --production=false
COPY tsconfig.json ./
COPY src/ ./src/
RUN npm run build

FROM node:20-slim
WORKDIR /app
RUN addgroup --system app && adduser --system --ingroup app app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY package*.json ./
USER app
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD curl -f http://localhost:3000/health || exit 1
CMD ["node", "dist/index.js"]

Step 2: Health Check Endpoint

// src/health.ts
import express from 'express';
import { MaintainXClient } from './client';

const app = express();

app.get('/health', async (req, res) => {
  const checks: Record<string, string> = {
    server: 'ok',
    apiKey: process.env.MAINTAINX_API_KEY ? 'configured' : 'missing',
  };

  try {
    const client = new MaintainXClient();
    await client.getUsers({ limit: 1 });
    checks.maintainxApi = 'ok';
  } catch (err: any) {
    checks.maintainxApi = `error: ${err.response?.status || err.message}`;
  }

  const allOk = Object.values(checks).every((v) => v === 'ok' || v === 'configured');
  res.status(allOk ? 200 : 503).json({
    status: allOk ? 'healthy' : 'degraded',
    checks,
    uptime: process.uptime(),
    timestamp: new Date().toISOString(),
  });
});

app.get('/ready', (req, res) => {
  res.status(process.env.MAINTAINX_API_KEY ? 200 : 503).json({
    ready: !!process.env.MAINTAINX_API_KEY,
  });
});

export { app };

Step 3: Deploy to Google Cloud Run

# Build and push container
PROJECT_ID="your-gcp-project"
REGION="us-central1"
SERVICE="maintainx-integration"

gcloud builds submit --tag gcr.io/$PROJECT_ID/$SERVICE

# Deploy with secrets
gcloud run deploy $SERVICE \
  --image gcr.io/$PROJECT_ID/$SERVICE \
  --region $REGION \
  --platform managed \
  --set-secrets "MAINTAINX_API_KEY=maintainx-api-key:latest" \
  --min-instances 1 \
  --max-instances 10 \
  --memory 512Mi \
  --cpu 1 \
  --port 3000 \
  --allow-unauthenticated  # Only if webhook endpoint

Step 4: Docker Compose for Multi-Service

# docker-compose.yml
services:
  ma

MaintainX Enterprise RBAC

Overview

Configure enterprise role-based access control for MaintainX integrations with role definitions, location-scoped permissions, and audit logging.

Prerequisites

• MaintainX Enterprise plan
• Understanding of RBAC concepts
• Node.js 18+

MaintainX Role Hierarchy

Organization Admin
├── can manage all locations, users, teams, and settings
├── Full API access
│
Location Manager
├── can manage work orders, assets at assigned locations
├── API: filtered by locationId
│
Technician
├── can view/update assigned work orders
├── API: filtered by assigneeId
│
Viewer (Read-Only)
└── can view work orders, assets, locations
    └── API: GET endpoints only

Instructions

Step 1: Role Definitions

// src/rbac/roles.ts

export type Role = 'admin' | 'manager' | 'technician' | 'viewer';

interface Permission {
  resource: string;
  actions: Array<'create' | 'read' | 'update' | 'delete'>;
  scope?: 'all' | 'location' | 'assigned';
}

export const ROLE_PERMISSIONS: Record<Role, Permission[]> = {
  admin: [
    { resource: 'workorders', actions: ['create', 'read', 'update', 'delete'], scope: 'all' },
    { resource: 'assets', actions: ['create', 'read', 'update', 'delete'], scope: 'all' },
    { resource: 'locations', actions: ['create', 'read', 'update', 'delete'], scope: 'all' },
    { resource: 'users', actions: ['create', 'read', 'update', 'delete'], scope: 'all' },
    { resource: 'teams', actions: ['create', 'read', 'update', 'delete'], scope: 'all' },
  ],
  manager: [
    { resource: 'workorders', actions: ['create', 'read', 'update'], scope: 'location' },
    { resource: 'assets', actions: ['create', 'read', 'update'], scope: 'location' },
    { resource: 'locations', actions: ['read'], scope: 'location' },
    { resource: 'users', actions: ['read'], scope: 'all' },
    { resource: 'teams', actions: ['read'], scope: 'all' },
  ],
  technician: [
    { resource: 'workorders', actions: ['read', 'update'], scope: 'assigned' },
    { resource: 'assets', actions: ['read'], scope: 'location' },
    { resource: 'locations', actions: ['read'], scope: 'location' },
  ],
  viewer: [
    { resource: 'workorders', actions: ['read'], scope: 'all' },
    { resource: 'assets', actions: ['read'],

MaintainX Hello World

Overview

Create your first work order using the MaintainX REST API -- the core building block of CMMS operations.

Prerequisites

• Completed maintainx-install-auth setup
• Valid MAINTAINXAPIKEY environment variable
• Node.js 18+ or curl

Instructions

Step 1: Create a Work Order (curl)

curl -X POST https://api.getmaintainx.com/v1/workorders \
  -H "Authorization: Bearer $MAINTAINX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Hello World - Test Work Order",
    "description": "First API-created work order. Safe to delete.",
    "priority": "LOW",
    "status": "OPEN"
  }' | jq .

Expected response:

{
  "id": 12345,
  "title": "Hello World - Test Work Order",
  "status": "OPEN",
  "priority": "LOW",
  "createdAt": "2026-03-19T12:00:00Z"
}

Step 2: Create a Work Order (TypeScript)

// hello-maintainx.ts
import { MaintainXClient } from './maintainx/client';

async function helloMaintainX() {
  const client = new MaintainXClient();

  // Create a basic work order
  const { data: workOrder } = await client.createWorkOrder({
    title: 'HVAC Filter Replacement - Building A',
    description: 'Replace air filters in units 1-4 on the 3rd floor.',
    priority: 'MEDIUM',
  });
  console.log('Created work order:', workOrder.id);

  // Retrieve it back to confirm
  const { data: fetched } = await client.getWorkOrder(workOrder.id);
  console.log('Work order status:', fetched.status);
  console.log('Created at:', fetched.createdAt);

  // List open work orders
  const { data: list } = await client.getWorkOrders({
    status: 'OPEN',
    limit: 5,
  });
  console.log(`Found ${list.workOrders.length} open work orders`);
}

helloMaintainX();

Step 3: Verify and Clean Up

# List recent work orders to confirm creation
curl -s "https://api.getmaintainx.com/v1/workorders?limit=3" \
  -H "Authorization: Bearer $MAINTAINX_API_KEY" | jq '.workOrders[] | {id, title, status}'

# Delete the test work order (replace ID)
curl -X DELETE "https://api.getmaintainx.com/v1/workorders/12345" \
  -H "Authorization: Bearer $MAINTAINX_API_KEY"

Output

• Working code file that creates a MaintainX work order via REST API
• Console output showing the created work order ID, status, and timestamp
• Verified retrieval of the created work order

Error Handling

Instructions

Step 1: Immediate Triage (First 5 Minutes)

#!/bin/bash
echo "=== MaintainX Incident Triage ==="
echo "Time: $(date -u)"

# Check MaintainX API status
echo -e "\n--- API Health ---"
for endpoint in users workorders assets locations; do
  CODE=$(curl -s -o /dev/null -w "%{http_code}" \
    "https://api.getmaintainx.com/v1/$endpoint?limit=1" \
    -H "Authorization: Bearer $MAINTAINX_API_KEY")
  echo "  /$endpoint: HTTP $CODE"
done

# Check your integration service
echo -e "\n--- Integration Service ---"
curl -s http://localhost:3000/health | jq . 2>/dev/null || echo "  Service unreachable"

# Check recent error logs
echo -e "\n--- Recent Errors (last 10 min) ---"
# Adjust for your log system:
# journalctl -u maintainx-sync --since "10 min ago" --no-pager | grep -i error | tail -10

Step 2: Determine Root Cause

Step 3: Apply Mitigation

API Key Expired (SEV-1):

# Gen

MaintainX Install & Auth

Overview

Set up MaintainX REST API authentication and configure your development environment for CMMS integration.

Prerequisites

• Node.js 18+ or Python 3.10+
• MaintainX account with API access (Professional or Enterprise plan)
• Admin access to generate API keys

Instructions

Step 1: Generate API Key

1. Log into MaintainX at https://app.getmaintainx.com
2. Navigate to Settings > Integrations
3. Click New Key > Generate Key
4. Copy and securely store your API key (shown only once)

Step 2: Configure Environment Variables

# Set environment variable
export MAINTAINX_API_KEY="your-api-key-here"

# Or create .env file
echo 'MAINTAINX_API_KEY=your-api-key' >> .env

# For multi-organization tokens, also set:
export MAINTAINX_ORG_ID="your-organization-id"

Step 3: Create API Client Wrapper

// src/maintainx/client.ts
import axios, { AxiosInstance, AxiosError } from 'axios';

export class MaintainXClient {
  private client: AxiosInstance;
  private baseUrl = 'https://api.getmaintainx.com/v1';

  constructor(apiKey?: string, orgId?: string) {
    const key = apiKey || process.env.MAINTAINX_API_KEY;
    if (!key) {
      throw new Error('MAINTAINX_API_KEY is required');
    }

    this.client = axios.create({
      baseURL: this.baseUrl,
      headers: {
        'Authorization': `Bearer ${key}`,
        'Content-Type': 'application/json',
        ...(orgId && { 'X-Organization-Id': orgId }),
      },
    });

    this.client.interceptors.response.use(
      response => response,
      this.handleError
    );
  }

  private handleError(error: AxiosError) {
    if (error.response) {
      const { status, data } = error.response;
      console.error(`MaintainX API Error [${status}]:`, data);
    }
    throw error;
  }

  // Core API methods
  async getWorkOrders(params?: WorkOrderQueryParams) {
    return this.client.get('/workorders', { params });
  }

  async getWorkOrder(id: string) {
    return this.client.get(`/workorders/${id}`);
  }

  async createWorkOrder(data: CreateWorkOrderInput) {
    return this.client.post('/workorders', data);
  }

  async getAssets(params?: AssetQueryParams) {
    return this.client.get('/assets', { params });
  }

  async getLocations(params?: LocationQueryParams) {
    return this.client.get('/locations', { params });
  }

  async getUsers(params?: UserQueryParams) {
    return this.client.get('/users', { params });
  }
}

// Type definitions
interface WorkOrderQueryParams {
  cursor?: string;
  limit?: number;
  status?: 'OPEN' | 'IN_PROGRESS' | 'ON_HOLD' | '

MaintainX Local Dev Loop

Overview

Set up an efficient local development workflow for building and testing MaintainX integrations with hot reload, mock servers, and automated testing.

Prerequisites

• Completed maintainx-install-auth setup
• Node.js 18+ installed
• MAINTAINXAPIKEY environment variable set

Instructions

Step 1: Initialize TypeScript Project

mkdir maintainx-integration && cd maintainx-integration
npm init -y
npm install axios dotenv
npm install -D typescript tsx vitest @types/node
npx tsc --init --target ES2022 --module NodeNext --moduleResolution nodenext --outDir dist

Create tsconfig.json paths:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "nodenext",
    "outDir": "dist",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["src/**/*"]
}

Step 2: Project Structure

maintainx-integration/
├── src/
│   ├── client.ts          # MaintainX API client (from install-auth)
│   ├── work-orders.ts     # Work order service layer
│   └── sync.ts            # Data sync logic
├── tests/
│   ├── client.test.ts     # Unit tests with mocks
│   └── integration.test.ts # Live API tests
├── .env                   # MAINTAINX_API_KEY=...
├── .env.example           # MAINTAINX_API_KEY=your-key-here
├── package.json
└── tsconfig.json

Step 3: Dev Scripts in package.json

{
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "test": "vitest run",
    "test:watch": "vitest",
    "test:integration": "INTEGRATION=true vitest run tests/integration.test.ts",
    "build": "tsc",
    "repl": "tsx src/repl.ts"
  }
}

Step 4: Write Unit Tests with Mocked API

// tests/client.test.ts
import { describe, it, expect, vi, beforeEach } from 'vitest';
import axios from 'axios';

vi.mock('axios');

describe('MaintainXClient', () => {
  beforeEach(() => {
    vi.resetAllMocks();
    process.env.MAINTAINX_API_KEY = 'test-key-123';
  });

  it('creates a work order', async () => {
    const mockResponse = {
      data: { id: 1, title: 'Test WO', status: 'OPEN' },
    };
    vi.mocked(axios.create).mockReturnValue({
      post: vi.fn().mockResolvedValue(mockResponse),
      interceptors: { response: { use: vi.fn() } },
    } as any);

    const { MaintainXClient } = await import('../src/client');
    const client = new 

MaintainX Migration Deep Dive

Current State

!node --version 2>/dev/null || echo 'N/A'

Overview

Comprehensive guide for migrating to MaintainX from legacy CMMS systems (Maximo, UpKeep, Fiix), spreadsheets, or custom databases.

Prerequisites

• MaintainX account with API access
• Access to source system data (CSV export, API, or database)
• Node.js 18+

Migration Phases

Phase 1: Assess    →  Phase 2: Map    →  Phase 3: Migrate  →  Phase 4: Validate
(Audit source)       (Schema mapping)    (ETL + import)        (Verify + cutover)

Instructions

Step 1: Source System Assessment

// scripts/assess-source.ts
import { parse } from 'csv-parse/sync';
import { readFileSync } from 'fs';

interface AssessmentReport {
  totalRecords: number;
  recordTypes: Record<string, number>;
  dataQuality: {
    missingFields: Record<string, number>;
    duplicates: number;
    invalidDates: number;
  };
}

function assessCSV(filePath: string, columns: string[]): AssessmentReport {
  const content = readFileSync(filePath, 'utf-8');
  const rows = parse(content, { columns: true, skip_empty_lines: true });

  const missing: Record<string, number> = {};
  const seen = new Set<string>();
  let duplicates = 0;
  let invalidDates = 0;

  for (const row of rows) {
    // Check missing fields
    for (const col of columns) {
      if (!row[col] || row[col].trim() === '') {
        missing[col] = (missing[col] || 0) + 1;
      }
    }

    // Check duplicates (by name/title)
    const key = row['Name'] || row['Title'] || row['name'];
    if (key && seen.has(key)) duplicates++;
    if (key) seen.add(key);

    // Check date formats
    for (const col of Object.keys(row)) {
      if (col.toLowerCase().includes('date') && row[col]) {
        if (isNaN(Date.parse(row[col]))) invalidDates++;
      }
    }
  }

  return {
    totalRecords: rows.length,
    recordTypes: { [filePath]: rows.length },
    dataQuality: { missingFields: missing, duplicates, invalidDates },
  };
}

// Run assessment
const report = assessCSV('legacy-work-orders.csv', ['Title', 'Priority', 'Status']);
console.log('=== Migration Assessment ===');
console.log(`Total records: ${report.totalRecords}`);
console.log('Missing fields:', report.dataQuality.missingFields);
console.log(`Duplicates: ${report.dataQuality.duplicates}`);
console.log(`Invalid dates: ${report.dataQuality.invalidDates}`);

Step 2: Schema Mapping

// src/migration/schema-map.ts

// Map legacy CMMS fields to MaintainX fields
interface FieldMapping {
  source: string;
  target: string;
  transform?: (value: any) => any;
}

const WORK_ORDER_MAP: FieldMapping[] = [
  {

MaintainX Multi-Environment Setup

Overview

Configure and manage multiple MaintainX environments for development, staging, and production with proper secret management and client isolation.

Prerequisites

• Separate MaintainX accounts or organizations for each environment
• Secret management solution (environment variables, GCP Secret Manager, or AWS SSM)
• Node.js 18+

Instructions

Step 1: Environment Configuration

// src/config/environments.ts

interface MaintainXEnvConfig {
  apiKey: string;
  orgId?: string;
  baseUrl: string;
  label: string;
  rateLimit: { requestsPerSecond: number };
}

type Environment = 'development' | 'staging' | 'production';

function getConfig(env: Environment): MaintainXEnvConfig {
  const configs: Record<Environment, () => MaintainXEnvConfig> = {
    development: () => ({
      apiKey: process.env.MAINTAINX_API_KEY_DEV!,
      orgId: process.env.MAINTAINX_ORG_ID_DEV,
      baseUrl: 'https://api.getmaintainx.com/v1',
      label: 'Development',
      rateLimit: { requestsPerSecond: 5 },
    }),
    staging: () => ({
      apiKey: process.env.MAINTAINX_API_KEY_STAGING!,
      orgId: process.env.MAINTAINX_ORG_ID_STAGING,
      baseUrl: 'https://api.getmaintainx.com/v1',
      label: 'Staging',
      rateLimit: { requestsPerSecond: 10 },
    }),
    production: () => ({
      apiKey: process.env.MAINTAINX_API_KEY_PROD!,
      orgId: process.env.MAINTAINX_ORG_ID_PROD,
      baseUrl: 'https://api.getmaintainx.com/v1',
      label: 'Production',
      rateLimit: { requestsPerSecond: 20 },
    }),
  };

  const config = configs[env]();
  if (!config.apiKey) {
    throw new Error(`Missing API key for ${env} environment`);
  }
  return config;
}

export const currentEnv = (process.env.MAINTAINX_ENV || 'development') as Environment;
export const config = getConfig(currentEnv);

Step 2: Client Factory

// src/client-factory.ts
import { MaintainXClient } from './client';

const clients = new Map<string, MaintainXClient>();

export function getClient(env?: Environment): MaintainXClient {
  const targetEnv = env || currentEnv;
  if (!clients.has(targetEnv)) {
    const cfg = getConfig(targetEnv);
    clients.set(targetEnv, new MaintainXClient(cfg.apiKey, cfg.orgId));
  }
  return clients.get(targetEnv)!;
}

// Usage
const devClient = getClient('development');
const prodClient = getClient('production');

Step 3: Environment Files

# .env.development
MAINTAINX_ENV=development
MAINTAINX_API_KEY_DEV=dev-key-here
MAINTAINX_ORG_ID_DEV=org-dev-123

# .env.staging
MAINTAINX_ENV=staging
MAINTAINX_API_KEY_STAGING=staging-key-here
MAINTAINX_ORG_ID_STAGING=org-staging-456

# .env.production
MAINTAI

MaintainX Observability

Overview

Implement metrics, structured logging, and alerting for MaintainX integrations to ensure reliability and rapid issue detection.

Prerequisites

• MaintainX integration deployed
• Node.js 18+
• Monitoring platform (Prometheus/Grafana, Datadog, or CloudWatch)

Instructions

Step 1: Prometheus Metrics

// src/observability/metrics.ts
import { Counter, Histogram, Gauge, Registry } from 'prom-client';

const register = new Registry();

export const metrics = {
  apiRequests: new Counter({
    name: 'maintainx_api_requests_total',
    help: 'Total MaintainX API requests',
    labelNames: ['method', 'endpoint', 'status'],
    registers: [register],
  }),

  apiLatency: new Histogram({
    name: 'maintainx_api_latency_seconds',
    help: 'MaintainX API request latency',
    labelNames: ['method', 'endpoint'],
    buckets: [0.1, 0.25, 0.5, 1, 2.5, 5, 10],
    registers: [register],
  }),

  rateLimitHits: new Counter({
    name: 'maintainx_rate_limit_hits_total',
    help: 'Times rate limited by MaintainX API',
    registers: [register],
  }),

  workOrdersProcessed: new Counter({
    name: 'maintainx_work_orders_processed_total',
    help: 'Work orders processed',
    labelNames: ['action', 'status'],
    registers: [register],
  }),

  syncLag: new Gauge({
    name: 'maintainx_sync_lag_seconds',
    help: 'Seconds since last successful sync',
    registers: [register],
  }),
};

export { register };

Step 2: Instrumented API Client

// src/observability/instrumented-client.ts
import axios, { AxiosInstance } from 'axios';
import { metrics } from './metrics';

export function createInstrumentedClient(apiKey: string): AxiosInstance {
  const client = axios.create({
    baseURL: 'https://api.getmaintainx.com/v1',
    headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
    timeout: 30_000,
  });

  client.interceptors.request.use((config) => {
    (config as any).__startTime = process.hrtime.bigint();
    return config;
  });

  client.interceptors.response.use(
    (response) => {
      const elapsed = Number(process.hrtime.bigint() - (response.config as any).__startTime) / 1e9;
      const endpoint = response.config.url?.split('?')[0] || 'unknown';

      metrics.apiRequests.inc({
        method: response.config.method?.toUpperCase() || 'GET',
        endpoint,
        status: String(response.status),
      });
      metrics.apiLatency.observe(
        { method: response.config.method?.toUpperCase() || 'GET', endpoint },
        elapsed,
      );
      return response;
    },
    (error) => {
      const 

MaintainX Performance Tuning

Overview

Optimize MaintainX integration performance with caching, connection pooling, efficient pagination, and request deduplication.

Prerequisites

• MaintainX integration working
• Node.js 18+
• Redis (recommended for production caching)
• Performance baseline measurements

Instructions

Step 1: Connection Pooling with Keep-Alive

// src/performance/pooled-client.ts
import axios from 'axios';
import http from 'node:http';
import https from 'node:https';

// Reuse TCP connections instead of opening new ones per request
const httpAgent = new http.Agent({ keepAlive: true, maxSockets: 10 });
const httpsAgent = new https.Agent({ keepAlive: true, maxSockets: 10 });

const client = axios.create({
  baseURL: 'https://api.getmaintainx.com/v1',
  headers: {
    Authorization: `Bearer ${process.env.MAINTAINX_API_KEY}`,
    'Content-Type': 'application/json',
  },
  httpAgent,
  httpsAgent,
  timeout: 30_000,
});

// Benefit: Eliminates TCP handshake + TLS negotiation per request
// Typical improvement: 100-200ms saved per request

Step 2: Multi-Level Caching

// src/performance/cache.ts

interface CacheLayer<T> {
  get(key: string): Promise<T | undefined>;
  set(key: string, value: T, ttlMs: number): Promise<void>;
}

// L1: In-memory (fastest, per-process)
class MemoryCache<T> implements CacheLayer<T> {
  private store = new Map<string, { value: T; expiresAt: number }>();

  async get(key: string) {
    const entry = this.store.get(key);
    if (entry && entry.expiresAt > Date.now()) return entry.value;
    this.store.delete(key);
    return undefined;
  }

  async set(key: string, value: T, ttlMs: number) {
    this.store.set(key, { value, expiresAt: Date.now() + ttlMs });
  }
}

// L2: Redis (shared across processes)
class RedisCache<T> implements CacheLayer<T> {
  constructor(private redis: any) {}

  async get(key: string) {
    const data = await this.redis.get(`mx:${key}`);
    return data ? JSON.parse(data) : undefined;
  }

  async set(key: string, value: T, ttlMs: number) {
    await this.redis.setex(`mx:${key}`, Math.ceil(ttlMs / 1000), JSON.stringify(value));
  }
}

// Multi-level cache: check L1 first, then L2, then fetch
class MultiCache<T> {
  constructor(private l1: CacheLayer<T>, private l2: CacheLayer<T>) {}

  async getOrFetch(key: string, ttlMs: number, fetcher: () => Promise<T>): Promise<T> {
    // Check L1
    let value = await this.l1.get(key);
    if (value !== undefined) return value;

    // Check L2
    value = await this.l2.get(key);
    if (value !== undefined) {
      await this.l1.set(key, value, ttlMs / 2); // L1 shorter TTL
      return value;
    }

    // Fetch from API
    valu

MaintainX Production Checklist

Overview

Comprehensive pre-deployment and post-deployment checklist for MaintainX integrations covering security, reliability, observability, and data integrity.

Prerequisites

• MaintainX integration developed and tested
• Production MaintainX account with API access
• Deployment infrastructure ready (Cloud Run, K8s, or similar)

Instructions

Step 1: Authentication & Security

# Verify production API key works
curl -s -o /dev/null -w "HTTP %{http_code}" \
  https://api.getmaintainx.com/v1/users?limit=1 \
  -H "Authorization: Bearer $MAINTAINX_API_KEY_PROD"

# Verify no secrets in codebase
npx gitleaks detect --source . --no-git

• [ ] API key stored in secret manager (not env file or code)
• [ ] .env and *.key files in .gitignore
• [ ] Pre-commit hook blocking secret commits
• [ ] API key rotation schedule set (every 90 days)
• [ ] Input validation on all user-provided data (Zod or similar)

Step 2: Error Handling & Resilience

• [ ] Retry logic with exponential backoff for 429 and 5xx errors
• [ ] Retry-After header honored on 429 responses
• [ ] Circuit breaker for cascading failure prevention
• [ ] Graceful degradation when MaintainX API is down
• [ ] Request timeout set (30 seconds recommended)

// Verify retry logic is configured
const client = axios.create({
  baseURL: 'https://api.getmaintainx.com/v1',
  timeout: 30_000,  // 30 second timeout
  headers: { Authorization: `Bearer ${apiKey}` },
});

Step 3: Data Integrity

• [ ] Cursor-based pagination handles all list endpoints
• [ ] Idempotency keys on webhook handlers (prevent duplicate processing)
• [ ] Data sync state persisted (survives restarts)
• [ ] Reconciliation job runs daily to detect drift
• [ ] Work order status transitions follow valid paths only

Step 4: Observability

• [ ] Structured JSON logging (not console.log in production)
• [ ] API request metrics (count, latency, error rate)
• [ ] Health check endpoint (/health) returning API connectivity status
• [ ] Readiness probe (/ready) for container orchestration
• [ ] Alerting configured for error rate > 5%, latency > 5s, sync lag > 15min

Step 5: Performance

• [ ] Connection pooling with keep-alive enabled
• [ ] Response caching for static resources (users, locations, teams)
• [ ] Max page size (100) used for pagination
• [ ] Webhook-driven updates instead of polling where possible
• [ ] Rate limiting to stay within API quotas

Step 6: Deployment

• [ ]

MaintainX Reference Architecture

Overview

Production-grade architecture patterns for building scalable, maintainable integrations between MaintainX and enterprise systems (ERP, SCADA, data warehouses).

Prerequisites

• Understanding of distributed systems
• Cloud platform experience (GCP, AWS, or Azure)
• MaintainX API familiarity

Instructions

Step 1: Event-Driven Sync Architecture

The recommended architecture for most MaintainX integrations. Uses webhooks for real-time updates and scheduled jobs for reconciliation.

MaintainX API ──webhook──→ Cloud Run ──→ Pub/Sub ──→ Cloud Functions
                                              │
                                              ├──→ BigQuery (analytics)
                                              ├──→ ERP System (SAP, Oracle)
                                              └──→ Notification Service

// src/architecture/event-driven.ts
import express from 'express';
import { PubSub } from '@google-cloud/pubsub';

const app = express();
const pubsub = new PubSub();
const topic = pubsub.topic('maintainx-events');

// Webhook receiver publishes to Pub/Sub
app.post('/webhooks/maintainx', async (req, res) => {
  const { event, data } = req.body;

  await topic.publishMessage({
    data: Buffer.from(JSON.stringify({ event, data })),
    attributes: { event, resourceId: String(data.id) },
  });

  res.status(200).json({ status: 'queued' });
});

// Subscriber processes events asynchronously
const subscription = pubsub.subscription('maintainx-events-sub');
subscription.on('message', async (message) => {
  const { event, data } = JSON.parse(message.data.toString());

  switch (event) {
    case 'workorder.completed':
      await syncToERP(data);
      await updateAnalytics(data);
      break;
    case 'workorder.created':
      if (data.priority === 'HIGH') {
        await sendUrgentNotification(data);
      }
      break;
  }

  message.ack();
});

Step 2: Bi-Directional Sync Gateway

For integrating MaintainX with ERP systems (SAP, Oracle) where changes flow both ways.

ERP (SAP/Oracle) ←──→ Sync Gateway ←──→ MaintainX API
                          │
                    Conflict Resolution
                    + Audit Trail
                    + Sync State DB

// src/architecture/sync-gateway.ts

interface SyncRecord {
  externalId: string;     // ERP system ID
  maintainxId: number;    // MaintainX ID
  lastSyncAt: string;
  syncDirection: 'inbound' | 'outbound' | 'bidirectional';
  hash: string;           // Content hash for change detection
}

class SyncGateway {
  constructor(
    private maintainx: MaintainXClient,
    private erp: ERPClient,
    private db: Syn

MaintainX SDK Patterns

Overview

Production-grade patterns for building robust MaintainX API integrations with proper error handling, cursor-based pagination, retry logic, and type safety.

Prerequisites

• Completed maintainx-install-auth setup
• TypeScript/Node.js familiarity
• Understanding of REST API principles

Instructions

Step 1: Type-Safe Client with Generics

// src/maintainx/typed-client.ts
import axios, { AxiosInstance, AxiosRequestConfig, AxiosError } from 'axios';

interface PaginatedResponse<T> {
  cursor: string | null;
}

interface WorkOrder {
  id: number;
  title: string;
  status: 'OPEN' | 'IN_PROGRESS' | 'ON_HOLD' | 'COMPLETED' | 'CLOSED';
  priority: 'NONE' | 'LOW' | 'MEDIUM' | 'HIGH';
  description?: string;
  assignees: Array<{ type: 'USER' | 'TEAM'; id: number }>;
  assetId?: number;
  locationId?: number;
  createdAt: string;
  updatedAt: string;
  completedAt?: string;
  dueDate?: string;
  categories: string[];
}

interface Asset {
  id: number;
  name: string;
  serialNumber?: string;
  model?: string;
  manufacturer?: string;
  locationId?: number;
  createdAt: string;
}

interface WorkOrdersResponse extends PaginatedResponse<WorkOrder> {
  workOrders: WorkOrder[];
}

interface AssetsResponse extends PaginatedResponse<Asset> {
  assets: Asset[];
}

export class MaintainXClient {
  private http: AxiosInstance;

  constructor(apiKey?: string) {
    const key = apiKey || process.env.MAINTAINX_API_KEY;
    if (!key) throw new Error('MAINTAINX_API_KEY required');

    this.http = axios.create({
      baseURL: 'https://api.getmaintainx.com/v1',
      headers: { Authorization: `Bearer ${key}`, 'Content-Type': 'application/json' },
      timeout: 30_000,
    });
  }

  async getWorkOrders(params?: Record<string, any>): Promise<WorkOrdersResponse> {
    const { data } = await this.http.get<WorkOrdersResponse>('/workorders', { params });
    return data;
  }

  async getWorkOrder(id: number): Promise<WorkOrder> {
    const { data } = await this.http.get<WorkOrder>(`/workorders/${id}`);
    return data;
  }

  async createWorkOrder(input: Partial<WorkOrder>): Promise<WorkOrder> {
    const { data } = await this.http.post<WorkOrder>('/workorders', input);
    return data;
  }

  async updateWorkOrder(id: number, input: Partial<WorkOrder>): Promise<WorkOrder> {
    const { data } = await this.http.patch<WorkOrder>(`/workorders/${id}`, input);
    return data;
  }

  async getAssets(params?: Record<string, any>): Promise<AssetsResponse> {
    const { data } = await this.http.get<AssetsResponse>('/assets', { params });
    return data;
  }

  async req

MaintainX Security Basics

Overview

Secure your MaintainX integration with proper credential management, input validation, audit logging, and key rotation procedures.

Prerequisites

• MaintainX account with admin access
• Node.js 18+
• Familiarity with environment variables and secret management

Instructions

Step 1: Secure Credential Storage

Never hardcode API keys. Use environment variables or a secret manager.

# .env (never committed to git)
MAINTAINX_API_KEY=mx-prod-key-here

# .gitignore
.env
.env.*
*.key

// src/config.ts - load and validate credentials
import 'dotenv/config';

const REQUIRED_VARS = ['MAINTAINX_API_KEY'] as const;

export function validateEnv() {
  const missing = REQUIRED_VARS.filter((v) => !process.env[v]);
  if (missing.length > 0) {
    throw new Error(`Missing required env vars: ${missing.join(', ')}`);
  }
}

validateEnv();
export const API_KEY = process.env.MAINTAINX_API_KEY!;

Step 2: Git Hook to Prevent Secret Commits

# Install pre-commit hook
cat > .git/hooks/pre-commit << 'HOOK'
#!/bin/bash
# Block commits containing API keys
if git diff --cached --diff-filter=ACMR | grep -qiE '(MAINTAINX_API_KEY|Bearer mx-)'; then
  echo "ERROR: Potential MaintainX API key detected in staged files."
  echo "Remove secrets before committing."
  exit 1
fi
HOOK
chmod +x .git/hooks/pre-commit

Or use gitleaks:

npx gitleaks detect --source . --no-git

Step 3: Input Validation

Validate all user input before sending to the MaintainX API:

// src/validation.ts
import { z } from 'zod';

const WorkOrderInput = z.object({
  title: z.string().min(1).max(500),
  description: z.string().max(5000).optional(),
  priority: z.enum(['NONE', 'LOW', 'MEDIUM', 'HIGH']).default('NONE'),
  status: z.enum(['OPEN', 'IN_PROGRESS', 'ON_HOLD', 'COMPLETED', 'CLOSED']).default('OPEN'),
  assignees: z.array(z.object({
    type: z.enum(['USER', 'TEAM']),
    id: z.number().positive(),
  })).optional(),
  assetId: z.number().positive().optional(),
  locationId: z.number().positive().optional(),
  dueDate: z.string().datetime().optional(),
});

export function validateWorkOrder(input: unknown) {
  return WorkOrderInput.parse(input);
}

// Usage
try {
  const validated = validateWorkOrder(userInput);
  await client.createWorkOrder(validated);
} catch (err) {
  if (err instanceof z.ZodError) {
    console.error('Validation failed:', err.issues);
  }
}

Step 4: Audit Logging

// src/au

MaintainX Upgrade & Migration

Current State

!npm list 2>/dev/null | head -20

Overview

Handle MaintainX API version upgrades, deprecations, and breaking changes with a safe, incremental migration strategy.

Prerequisites

• Existing MaintainX integration
• Test environment with separate API key
• Version control (git) for all integration code

Instructions

Step 1: Audit Current API Usage

// scripts/audit-api-usage.ts
// Scan your codebase for all MaintainX API calls

import { readFileSync, readdirSync, statSync } from 'fs';
import { join } from 'path';

function findApiCalls(dir: string): Array<{ file: string; line: number; endpoint: string }> {
  const results: Array<{ file: string; line: number; endpoint: string }> = [];

  function scan(d: string) {
    for (const entry of readdirSync(d)) {
      const full = join(d, entry);
      if (statSync(full).isDirectory()) {
        if (!entry.startsWith('.') && entry !== 'node_modules') scan(full);
      } else if (full.endsWith('.ts') || full.endsWith('.js')) {
        const content = readFileSync(full, 'utf-8');
        const lines = content.split('\n');
        for (let i = 0; i < lines.length; i++) {
          // Match API endpoint patterns
          const match = lines[i].match(/'"`[^'"`]*)/);
          if (match) {
            results.push({ file: full, line: i + 1, endpoint: match[1] });
          }
        }
      }
    }
  }

  scan(dir);
  return results;
}

const calls = findApiCalls('./src');
console.log('=== MaintainX API Usage Audit ===');
console.log(`Found ${calls.length} API calls:\n`);

// Group by endpoint
const grouped = new Map<string, typeof calls>();
for (const call of calls) {
  const base = call.endpoint.split('?')[0].replace(/\/\d+/, '/:id');
  const existing = grouped.get(base) || [];
  existing.push(call);
  grouped.set(base, existing);
}

for (const [endpoint, usages] of grouped) {
  console.log(`${endpoint} (${usages.length} calls):`);
  for (const u of usages) {
    console.log(`  ${u.file}:${u.line}`);
  }
}

Step 2: Version Compatibility Layer

// src/migration/compat.ts

type ApiVersion = 'v1' | 'v2';

interface VersionAdapter {
  baseUrl: string;
  transformRequest(endpoint: string, data: any): { endpoint: string; data: any };
  transformResponse(endpoint: string, data: any): any;
}

const adapters: Record<ApiVersion, VersionAdapter> = {
  v1: {
    baseUrl: 'https://api.getmaintainx.com/v1',
    transformRequest: (endpoint, data) => ({ endpoint, data }),
    transformResponse: (endpoint, data) => data,
  },
  v2: {
    baseUrl: 'https://api.getmaintainx.com/v2',
    transformRequest: (e

MaintainX Webhooks & Events

Overview

Build real-time integrations with MaintainX using webhooks for work order updates, asset changes, and maintenance notifications. MaintainX fires webhook events when key resources change.

Prerequisites

• MaintainX account with API access
• HTTPS endpoint accessible from the internet (ngrok for local dev)
• MAINTAINXAPIKEY environment variable configured

Instructions

Step 1: Register a Webhook

curl -X POST https://api.getmaintainx.com/v1/webhooks \
  -H "Authorization: Bearer $MAINTAINX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.example.com/webhooks/maintainx",
    "events": [
      "workorder.created",
      "workorder.updated",
      "workorder.status_changed",
      "workorder.completed"
    ]
  }'

Step 2: Webhook Receiver (Express)

// src/webhook-server.ts
import express from 'express';
import crypto from 'node:crypto';

const app = express();
app.use(express.json({ limit: '1mb' }));

// Signature verification middleware
function verifySignature(secret: string) {
  return (req: express.Request, res: express.Response, next: express.NextFunction) => {
    const signature = req.headers['x-maintainx-signature'] as string;
    if (!signature) {
      return res.status(401).json({ error: 'Missing signature header' });
    }

    const expected = crypto
      .createHmac('sha256', secret)
      .update(JSON.stringify(req.body))
      .digest('hex');

    if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
      return res.status(401).json({ error: 'Invalid signature' });
    }
    next();
  };
}

const WEBHOOK_SECRET = process.env.MAINTAINX_WEBHOOK_SECRET!;

app.post(
  '/webhooks/maintainx',
  verifySignature(WEBHOOK_SECRET),
  async (req, res) => {
    const { event, data, timestamp } = req.body;

    console.log(`[${timestamp}] Event: ${event}, Resource ID: ${data.id}`);

    // Idempotency check
    const eventId = req.headers['x-maintainx-event-id'] as string;
    if (await isProcessed(eventId)) {
      return res.status(200).json({ status: 'already_processed' });
    }

    try {
      await routeEvent(event, data);
      await markProcessed(eventId);
      res.status(200).json({ status: 'ok' });
    } catch (err) {
      console.error('Webhook handler error:', err);
      res.status(500).json({ error: 'Processing failed' });
    }
  },
);

app.listen(3000, () => console.log('Webhook server listening on :3000'));

Step 3: Event Router

// src/event-handlers.ts

type EventH