@openmrs/esm-report-builder 0.1.1-pre.101

package/src/resources/etl-monitor/etl-monitor.api.ts

@@ -0,0 +1,381 @@
+import { openmrsFetch, restBaseUrl } from '@openmrs/esm-framework';
+import { omrsDelete, omrsGet, omrsPost } from '../openmrs-api';
+import type {
+    ETLMonitorDto,
+    SaveETLMonitorPayload,
+    MonitorDataResponse,
+} from '../../types/etl-monitor/etl-monitor.types';
+
+type RestList<T> = { results?: T[] } & Record<string, any>;
+
+function unwrapRestList<T>(data: RestList<T> | T[] | undefined): T[] {
+    if (!data) return [];
+    if (Array.isArray(data)) return data;
+    return Array.isArray(data.results) ? data.results : [];
+}
+
+const RESOURCE = '/reportbuilder/etl-monitor';
+
+/**
+ * List all ETL monitors
+ */
+export async function listETLMonitors(q?: string, signal?: AbortSignal): Promise<ETLMonitorDto[]> {
+    const qs = new URLSearchParams();
+    qs.set('v', 'full');
+    if (q?.trim()) qs.set('q', q.trim());
+
+    const data = await omrsGet<RestList<ETLMonitorDto> | ETLMonitorDto[] | undefined>(
+        `${RESOURCE}?${qs.toString()}`,
+        signal,
+    );
+
+    return unwrapRestList(data).filter((x) => Boolean(x?.uuid));
+}
+
+/**
+ * List active ETL monitors
+ */
+export async function listActiveETLMonitors(signal?: AbortSignal): Promise<ETLMonitorDto[]> {
+    const qs = new URLSearchParams();
+    qs.set('v', 'full');
+    qs.set('activeOnly', 'true');
+
+    const data = await omrsGet<RestList<ETLMonitorDto> | ETLMonitorDto[] | undefined>(
+        `${RESOURCE}?${qs.toString()}`,
+        signal,
+    );
+
+    return unwrapRestList(data).filter((x) => Boolean(x?.uuid));
+}
+
+/**
+ * Get ETL monitors by category
+ */
+export async function getETLMonitorsByCategory(category: string, signal?: AbortSignal): Promise<ETLMonitorDto[]> {
+    const qs = new URLSearchParams();
+    qs.set('v', 'full');
+    qs.set('category', category);
+
+    const data = await omrsGet<RestList<ETLMonitorDto> | ETLMonitorDto[] | undefined>(
+        `${RESOURCE}?${qs.toString()}`,
+        signal,
+    );
+
+    return unwrapRestList(data).filter((x) => Boolean(x?.uuid));
+}
+
+/**
+ * Get a single ETL monitor by UUID
+ */
+export async function getETLMonitor(uuid: string, signal?: AbortSignal): Promise<ETLMonitorDto> {
+    const qs = new URLSearchParams();
+    qs.set('v', 'full');
+
+    return omrsGet<ETLMonitorDto>(`${RESOURCE}/${encodeURIComponent(uuid)}?${qs.toString()}`, signal);
+}
+
+/**
+ * Create a new ETL monitor
+ */
+export async function createETLMonitor(payload: SaveETLMonitorPayload, signal?: AbortSignal) {
+    return omrsPost<ETLMonitorDto>(RESOURCE, payload, signal);
+}
+
+/**
+ * Update an existing ETL monitor
+ */
+export async function updateETLMonitor(uuid: string, payload: SaveETLMonitorPayload, signal?: AbortSignal) {
+    return omrsPost<ETLMonitorDto>(`${RESOURCE}/${encodeURIComponent(uuid)}`, payload, signal);
+}
+
+/**
+ * Delete/retire an ETL monitor
+ */
+export async function deleteETLMonitor(
+    uuid: string,
+    reason = 'Retired from Report Builder Admin',
+    signal?: AbortSignal,
+) {
+    const qs = new URLSearchParams();
+    qs.set('reason', reason);
+    return omrsDelete(`${RESOURCE}/${encodeURIComponent(uuid)}?${qs.toString()}`, signal);
+}
+
+/**
+ * Extract value from object using a simple JSONPath-like expression
+ * Supports: $.field, $.field.nested, $[0].field
+ */
+function extractValue(obj: any, jsonPath: string): any {
+    if (!jsonPath || !obj) return undefined;
+
+    // Remove leading $. if present
+    const path = jsonPath.startsWith('$.') ? jsonPath.slice(2) : jsonPath;
+
+    // Split by . but handle array notation [0]
+    const parts = path.split('.').flatMap(p => {
+        const arrayMatch = p.match(/^(\w+)\[(\d+)\]$/);
+        if (arrayMatch) {
+            return [arrayMatch[1], parseInt(arrayMatch[2], 10)];
+        }
+        return [p];
+    });
+
+    let current = obj;
+    for (const part of parts) {
+        if (current == null) return undefined;
+        current = current[part];
+    }
+
+    return current;
+}
+
+/**
+ * Transform raw API response using display configuration
+ * Converts structured JSON into array of {key, value} objects
+ */
+function transformApiResponse(rawResponse: any, displayConfigJson?: string): Array<{
+    key: string;
+    header: string;
+    value: any;
+    displayValue?: string;
+    rawValue?: any;
+}> {
+    if (!rawResponse) return [];
+
+    // If no display config, try to return array-friendly structure
+    if (!displayConfigJson) {
+        if (Array.isArray(rawResponse)) {
+            return rawResponse;
+        }
+        // Convert object to array of key-value pairs
+        return Object.entries(rawResponse).map(([key, value]) => ({
+            key,
+            header: key,
+            value,
+        }));
+    }
+
+    try {
+        const config = JSON.parse(displayConfigJson);
+        const columns = config.columns || [];
+
+        return columns.map((col: any) => {
+            const value = extractValue(rawResponse, col.jsonPath);
+            return {
+                key: col.key,
+                header: col.header,
+                value: value ?? col.defaultValue,
+                displayValue: col.format ? applyFormat(value, col.format) : undefined,
+                rawValue: value,
+            };
+        });
+    } catch (e) {
+        console.error('Failed to parse display config JSON', e);
+        return [];
+    }
+}
+
+/**
+ * Apply format string to a value
+ */
+function applyFormat(value: any, format: string): string {
+    if (value == null) return '';
+
+    // Handle common format patterns
+    if (format.includes('%')) {
+        return String(Math.round(Number(value) || 0)) + '%';
+    }
+    if (format.includes('s')) {
+        return String(value) + 's';
+    }
+    if (format === '0.0') {
+        return String(Math.round(Number(value) * 10) / 10);
+    }
+
+    return String(value);
+}
+
+/**
+ * Fetch data from the external ETL endpoint
+ * Uses OpenMRS's openmrsFetch which handles authentication automatically
+ */
+export async function fetchMonitorData(uuid: string, signal?: AbortSignal): Promise<MonitorDataResponse> {
+    // First, get the monitor configuration
+    const monitor = await getETLMonitor(uuid, signal);
+
+    if (!monitor || !monitor.configJson) {
+        throw new Error('Monitor configuration not found');
+    }
+
+    // Parse the config to get the ETL endpoint details
+    const config = JSON.parse(monitor.configJson);
+    const apiEndpoint = config.apiEndpoint;
+
+    if (!apiEndpoint || !apiEndpoint.url) {
+        throw new Error('ETL endpoint URL not configured');
+    }
+
+    // Construct the URL - if relative, prepend with OpenMRS REST base
+    let url = apiEndpoint.url;
+    if (url.startsWith('/')) {
+        // Prepend with restBaseUrl (/ws/rest/v1) for relative URLs
+        url = `${restBaseUrl}${url}`;
+    }
+
+    // Prepare fetch options for openmrsFetch
+    const headers: Record<string, string> = {};
+
+    // Add request body for POST requests
+    const body = apiEndpoint.method === 'POST' && apiEndpoint.requestBody
+        ? JSON.stringify(apiEndpoint.requestBody)
+        : undefined;
+
+    // Add any custom headers from config
+    if (apiEndpoint.headers) {
+        Object.entries(apiEndpoint.headers).forEach(([key, value]) => {
+            headers[key] = String(value);
+        });
+    }
+
+    // Add authentication headers (except for OPENMRS which is handled by openmrsFetch)
+    if (apiEndpoint.authType === 'BASIC' && apiEndpoint.authConfig) {
+        const credentials = btoa(`${apiEndpoint.authConfig.username}:${apiEndpoint.authConfig.password}`);
+        headers['Authorization'] = `Basic ${credentials}`;
+    } else if (apiEndpoint.authType === 'BEARER_TOKEN' && apiEndpoint.authConfig?.token) {
+        headers['Authorization'] = `Bearer ${apiEndpoint.authConfig.token}`;
+    } else if (apiEndpoint.authType === 'API_KEY' && apiEndpoint.authConfig) {
+        const { headerName, apiKey } = apiEndpoint.authConfig;
+        if (headerName && apiKey) {
+            headers[headerName] = apiKey;
+        }
+    }
+
+    // Use openmrsFetch which handles OpenMRS session authentication automatically
+    const response = await openmrsFetch<any>(url, {
+        method: apiEndpoint.method || 'GET',
+        headers,
+        body,
+        signal,
+    });
+
+    // Transform the API response using display configuration
+    const transformedData = transformApiResponse(response.data, monitor.displayConfigJson);
+
+    // Return in the expected format
+    return {
+        uuid: monitor.uuid,
+        code: monitor.code || '',
+        timestamp: new Date().toISOString(),
+        success: true,
+        data: transformedData,
+        rawResponse: response.data,
+    };
+}
+
+/**
+ * Test connection to the external ETL endpoint
+ * Uses openmrsFetch which handles authentication automatically
+ */
+export async function testMonitorConnection(uuid: string, signal?: AbortSignal): Promise<{
+    success: boolean;
+    message?: string;
+    error?: string;
+    responseTime?: number;
+}> {
+    const startTime = Date.now();
+
+    try {
+        // First, get the monitor configuration
+        const monitor = await getETLMonitor(uuid, signal);
+
+        if (!monitor || !monitor.configJson) {
+            return {
+                success: false,
+                error: 'Monitor configuration not found',
+                responseTime: Date.now() - startTime,
+            };
+        }
+
+        // Parse the config to get the ETL endpoint details
+        const config = JSON.parse(monitor.configJson);
+        const apiEndpoint = config.apiEndpoint;
+
+        if (!apiEndpoint || !apiEndpoint.url) {
+            return {
+                success: false,
+                error: 'ETL endpoint URL not configured',
+                responseTime: Date.now() - startTime,
+            };
+        }
+
+        // Construct the URL - if relative, prepend with OpenMRS REST base
+        let url = apiEndpoint.url;
+        if (url.startsWith('/')) {
+            // Prepend with restBaseUrl (/ws/rest/v1) for relative URLs
+            url = `${restBaseUrl}${url}`;
+        }
+
+        // Prepare fetch options for openmrsFetch
+        const headers: Record<string, string> = {};
+
+        // Add request body for POST requests
+        const body = apiEndpoint.method === 'POST' && apiEndpoint.requestBody
+            ? JSON.stringify(apiEndpoint.requestBody)
+            : undefined;
+
+        // Add any custom headers from config
+        if (apiEndpoint.headers) {
+            Object.entries(apiEndpoint.headers).forEach(([key, value]) => {
+                headers[key] = String(value);
+            });
+        }
+
+        // Add authentication headers (except for OPENMRS which is handled by openmrsFetch)
+        if (apiEndpoint.authType === 'BASIC' && apiEndpoint.authConfig) {
+            const credentials = btoa(`${apiEndpoint.authConfig.username}:${apiEndpoint.authConfig.password}`);
+            headers['Authorization'] = `Basic ${credentials}`;
+        } else if (apiEndpoint.authType === 'BEARER_TOKEN' && apiEndpoint.authConfig?.token) {
+            headers['Authorization'] = `Bearer ${apiEndpoint.authConfig.token}`;
+        } else if (apiEndpoint.authType === 'API_KEY' && apiEndpoint.authConfig) {
+            const { headerName, apiKey } = apiEndpoint.authConfig;
+            if (headerName && apiKey) {
+                headers[headerName] = apiKey;
+            }
+        }
+
+        // Use openmrsFetch which handles OpenMRS session authentication automatically
+        await openmrsFetch<any>(url, {
+            method: apiEndpoint.method || 'GET',
+            headers,
+            body,
+            signal,
+        });
+        const responseTime = Date.now() - startTime;
+
+        return {
+            success: true,
+            message: 'Connection successful',
+            responseTime,
+        };
+
+    } catch (error: any) {
+        return {
+            success: false,
+            error: error.message || 'Connection failed',
+            responseTime: Date.now() - startTime,
+        };
+    }
+}
+
+// Re-export endpoint test functions
+export {
+    testEndpointConnection,
+    testEndpointConnectionClientSide,
+    isJsonResponse,
+    getContentTypeLabel,
+    formatDuration,
+    formatContentSize,
+    getHttpStatusLabel,
+    type EndpointTestRequest,
+    type EndpointTestResult,
+} from './etl-monitor-test.api';

package/src/resources/etl-source/etl-source.api.ts

@@ -0,0 +1,65 @@
+import { omrsDelete, omrsGet, omrsPost } from '../openmrs-api';
+
+type RestList<T> = { results?: T[] } & Record<string, any>;
+
+function unwrapRestList<T>(data: RestList<T> | T[] | undefined): T[] {
+  if (!data) return [];
+  if (Array.isArray(data)) return data;
+  return Array.isArray(data.results) ? data.results : [];
+}
+
+const RESOURCE = '/reportbuilder/etlsource';
+
+export type ETLSourceDto = {
+  uuid: string;
+  display?: string;
+  name: string;
+  code?: string;
+  description?: string;
+  tablePatterns?: string;
+  schemaName?: string;
+  sourceType?: string;
+  active?: boolean;
+  voided?: boolean;
+};
+
+export type SaveETLSourcePayload = {
+  name: string;
+  code?: string;
+  description?: string;
+  tablePatterns?: string;
+  schemaName?: string;
+  sourceType?: string;
+  active?: boolean;
+};
+
+export async function listETLSources(q?: string, signal?: AbortSignal): Promise<ETLSourceDto[]> {
+  const qs = new URLSearchParams();
+  qs.set('v', 'custom:(uuid,name,code,description,tablePatterns,schemaName,sourceType,active,retired)');
+  if (q?.trim()) qs.set('q', q.trim());
+
+  const data = await omrsGet<RestList<ETLSourceDto> | ETLSourceDto[] | undefined>(
+    `${RESOURCE}?${qs.toString()}`,
+    signal,
+  );
+
+  return unwrapRestList(data).filter((x) => Boolean(x?.uuid));
+}
+
+export async function createETLSource(payload: SaveETLSourcePayload, signal?: AbortSignal) {
+  return omrsPost<ETLSourceDto>(RESOURCE, payload, signal);
+}
+
+export async function updateETLSource(uuid: string, payload: SaveETLSourcePayload, signal?: AbortSignal) {
+  return omrsPost<ETLSourceDto>(`${RESOURCE}/${encodeURIComponent(uuid)}`, payload, signal);
+}
+
+export async function deleteETLSource(
+  uuid: string,
+  reason = 'Retired from Report Builder Admin',
+  signal?: AbortSignal,
+) {
+  const qs = new URLSearchParams();
+  qs.set('reason', reason);
+  return omrsDelete(`${RESOURCE}/${encodeURIComponent(uuid)}?${qs.toString()}`, signal);
+}

package/src/resources/etl-task/etl-task.api.ts

@@ -0,0 +1,96 @@
+/**
+ * ETL Task API integration
+ * Handles fetching and executing ETL tasks using frontend config
+ */
+
+import { openmrsFetch } from '@openmrs/esm-framework';
+import type { OpenMRSTaskDefinition, ETLTaskExecutionResponse } from './etl-task.types';
+
+// These are OpenMRS core endpoints (scheduler), not reportbuilder ones - a 403 here
+// carries a core privilege name, which the error normalizer passes through verbatim.
+import { guardRejection } from '../../utils/api-error.utils';
+
+/**
+ * Fetch all available OpenMRS task definitions (with scheduler metadata)
+ */
+export async function fetchAllTaskDefinitions(signal?: AbortSignal): Promise<OpenMRSTaskDefinition[]> {
+  try {
+    const response = await guardRejection(
+      openmrsFetch(
+        '/ws/rest/v1/taskdefinition?v=custom:(uuid,name,description,taskClass,started,lastExecutionTime,repeatInterval)',
+        { signal },
+      ),
+    );
+    const data = await response.json();
+    return data.results || [];
+  } catch (error) {
+    console.error('Error fetching task definitions:', error);
+    throw error;
+  }
+}
+
+export interface ConfiguredTasksResult {
+  /** Configured names that matched a task definition, in fetch order */
+  tasks: OpenMRSTaskDefinition[];
+  /** Configured names with no matching task definition */
+  unknownNames: string[];
+}
+
+/**
+ * Fetch the task definitions for a list of configured task names,
+ * partitioning into matched definitions and unknown configured names.
+ * Matching is exact and case-sensitive so config typos surface as unknown names.
+ */
+export async function fetchConfiguredTasks(
+  taskNames: string[],
+  signal?: AbortSignal,
+): Promise<ConfiguredTasksResult> {
+  const names = taskNames.map((n) => (typeof n === 'string' ? n.trim() : '')).filter((n) => n);
+  if (names.length === 0) return { tasks: [], unknownNames: [] };
+
+  const allTasks = await fetchAllTaskDefinitions(signal);
+
+  const matched = new Set<string>();
+  const tasks: OpenMRSTaskDefinition[] = [];
+  for (const task of allTasks) {
+    if (names.includes(task.name)) {
+      tasks.push(task);
+      matched.add(task.name);
+    }
+  }
+
+  const unknownNames = names.filter((n) => !matched.has(n));
+  return { tasks, unknownNames };
+}
+
+/**
+ * Execute an ETL task by name
+ */
+export async function executeETLTask(taskName: string): Promise<ETLTaskExecutionResponse> {
+  try {
+    const response = await guardRejection(
+      openmrsFetch('/ws/rest/v1/taskaction', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: {
+          action: 'runtask',
+          tasks: [taskName],
+        },
+      }),
+    );
+
+    if (response.status !== 201) {
+      throw new Error(`Task execution failed with status ${response.status}`);
+    }
+
+    return {
+      status: response.status,
+      message: 'Task executed successfully',
+    };
+  } catch (error) {
+    console.error('Error executing ETL task:', error);
+    throw error;
+  }
+}

package/src/resources/etl-task/etl-task.types.ts

@@ -0,0 +1,31 @@
+/**
+ * ETL Task configuration and execution types
+ */
+
+export interface OpenMRSTaskDefinition {
+  uuid: string;
+  name: string;
+  description?: string;
+  taskClass: string;
+  /** Whether the task is started in the scheduler */
+  started?: boolean;
+  /** ISO-ish timestamp of the last execution */
+  lastExecutionTime?: string | null;
+  /** Repeat interval in seconds; 0/undefined means one-shot */
+  repeatInterval?: number | null;
+}
+
+/**
+ * Shape of the `etlTasks` frontend config option
+ */
+export interface ETLTasksConfig {
+  /** Names of existing OpenMRS task definitions to list and run */
+  tasks: string[];
+  /** ETL monitor codes (preferred) or uuids whose live progress shows above the task list */
+  progressMonitors?: string[];
+}
+
+export interface ETLTaskExecutionResponse {
+  status: number;
+  message?: string;
+}

package/src/resources/indicator/indicators.api.ts

@@ -0,0 +1,125 @@
+import { omrsDelete, omrsGet, omrsPost } from '../openmrs-api';
+import { decodeHtmlEntities } from '../../utils/html-entities.utils';
+
+/**
+ * REST resource:
+ *  /ws/rest/v1/reportbuilderindicator
+ */
+const RESOURCE = '/reportbuilder/indicator';
+
+type RestList<T> = { results?: T[] } & Record<string, any>;
+
+function unwrapRestList<T>(data: RestList<T> | T[] | undefined): T[] {
+    if (!data) return [];
+    if (Array.isArray(data)) return data;
+    return Array.isArray(data.results) ? data.results : [];
+}
+
+function normalizeIndicatorDto(ind: IndicatorDto): IndicatorDto {
+    // OpenMRS can return HTML-escaped strings; decode before UI uses them.
+    return {
+        ...ind,
+        configJson: ind.configJson ? decodeHtmlEntities(ind.configJson) : ind.configJson,
+        metaJson: ind.metaJson ? decodeHtmlEntities(ind.metaJson) : ind.metaJson,
+        sqlTemplate: ind.sqlTemplate ? decodeHtmlEntities(ind.sqlTemplate) : ind.sqlTemplate,
+        denominatorSqlTemplate: ind.denominatorSqlTemplate
+            ? decodeHtmlEntities(ind.denominatorSqlTemplate)
+            : ind.denominatorSqlTemplate,
+    };
+}
+
+export type IndicatorKind = 'BASE' | 'COMPOSITE' | 'FINAL' | 'CUSTOM';
+export type IndicatorValueType = 'NUMBER' | 'TABLE' | 'PATIENT_SET';
+export type RestRep = 'default' | 'full';
+
+export type IndicatorDto = {
+    uuid: string;
+    name: string;
+    description?: string;
+    code?: string;
+
+    kind: IndicatorKind;
+    defaultValueType?: IndicatorValueType;
+
+    // new-ish fields you’re adding backend-side (safe optional)
+    themeUuid?: string | null;
+    configJson?: string;
+    metaJson?: string;
+    sqlTemplate?: string | null;
+    denominatorSqlTemplate?: string | null;
+
+    retired?: boolean;
+    retireReason?: string | null;
+};
+
+export type ETLIndicatorDto = {
+    id: string,
+    uuid: string;
+    name: string;
+    description?: string;
+    code?: string;
+
+    kind: IndicatorKind;
+    defaultValueType?: IndicatorValueType;
+    themeName?: string;
+    themeColor?: string;
+
+    // new-ish fields you’re adding backend-side (safe optional)
+    themeUuid?: string | null;
+    configJson?: string;
+    metaJson?: string;
+    sqlTemplate?: string | null;
+    denominatorSqlTemplate?: string | null;
+
+    retired?: boolean;
+    retireReason?: string | null;
+};
+
+export type ListIndicatorsParams = {
+    q?: string;
+    kind?: IndicatorKind;
+    includeRetired?: boolean;
+    v?: RestRep;
+};
+
+export async function listIndicators(params?: ListIndicatorsParams, signal?: AbortSignal): Promise<IndicatorDto[]> {
+    const q = params?.q?.trim();
+    const kind = params?.kind?.trim?.() ? params.kind : params?.kind;
+    const includeRetired = params?.includeRetired === true;
+    const v = params?.v ?? 'default';
+
+    const qs = new URLSearchParams();
+    qs.set('v', v);
+    if (q) qs.set('q', q);
+    if (kind) qs.set('kind', kind);
+    if (includeRetired) qs.set('includeRetired', 'true');
+
+    const data = await omrsGet<RestList<IndicatorDto> | IndicatorDto[] | undefined>(`${RESOURCE}?${qs.toString()}`, signal);
+
+    return unwrapRestList(data)
+        .filter((x) => Boolean(x?.uuid))
+        .map(normalizeIndicatorDto);
+}
+
+export async function getIndicator(uuid: string, signal?: AbortSignal, v: RestRep = 'full'): Promise<IndicatorDto> {
+    const res = await omrsGet<IndicatorDto>(`${RESOURCE}/${encodeURIComponent(uuid)}?v=${v}`, signal);
+    return normalizeIndicatorDto(res);
+}
+
+export async function createIndicator(payload: Partial<IndicatorDto>, signal?: AbortSignal): Promise<IndicatorDto> {
+    return omrsPost<IndicatorDto>(RESOURCE, payload, signal);
+}
+
+export async function updateIndicator(uuid: string, payload: Partial<IndicatorDto>, signal?: AbortSignal): Promise<IndicatorDto> {
+    return omrsPost<IndicatorDto>(`${RESOURCE}/${encodeURIComponent(uuid)}`, payload, signal);
+}
+
+export async function deleteIndicator(
+    uuid: string,
+    purge = false,
+    reason = 'Retired via UI',
+    signal?: AbortSignal,
+): Promise<void> {
+    const qs = purge ? `purge=true` : `purge=false&reason=${encodeURIComponent(reason)}`;
+    await omrsDelete<void>(`${RESOURCE}/${encodeURIComponent(uuid)}?${qs}`, signal);
+}