@kenyaemr/esm-etims-app 5.4.5-pre.1109

package/src/routes.json

@@ -0,0 +1,117 @@
+{
+  "$schema": "https://json.openmrs.org/routes.schema.json",
+  "backendDependencies": {
+    "kenyaemr.cashier": "^4.2.8-SNAPSHOT"
+  },
+  "pages": [
+    {
+      "component": "root",
+      "route": "etims",
+      "online": true,
+      "offline": false
+    }
+  ],
+  "extensions": [
+    {
+      "component": "etimsLeftPanelLink",
+      "name": "etims-left-panel-link",
+      "slot": "etims-left-panel-slot"
+    },
+    {
+      "component": "etimsReferenceDataLeftPanelLink",
+      "name": "etims-reference-data-left-panel-link",
+      "slot": "etims-left-panel-slot"
+    },
+    {
+      "component": "etimsItemMappingLeftPanelLink",
+      "name": "etims-item-mapping-left-panel-link",
+      "slot": "etims-left-panel-slot"
+    },
+    {
+      "component": "etimsTransactionLeftPanelLink",
+      "name": "etims-transaction-left-panel-link",
+      "slot": "etims-left-panel-slot"
+    },
+    {
+      "component": "etimsCreditNoteLeftPanelLink",
+      "name": "etims-credit-note-left-panel-link",
+      "slot": "etims-left-panel-slot"
+    },
+    {
+      "component": "etimsGlobalPropertiesLeftPanelLink",
+      "name": "etims-global-properties-left-panel-link",
+      "slot": "etims-left-panel-slot"
+    },
+    {
+      "name": "etims-nav-link",
+      "slot": "navbar-items-slot",
+      "component": "etimsNavLink",
+      "order": 0,
+      "meta": {
+        "name": "etims",
+        "title": "eTims",
+        "search": ["etims", "eTims"]
+      }
+    }
+  ],
+  "modals": [
+    {
+      "name": "etims-void-item-mapping-modal",
+      "component": "etimsVoidItemMappingModal"
+    },
+    {
+      "name": "etims-register-item-mapping-modal",
+      "component": "etimsRegisterItemMappingModal"
+    },
+    {
+      "name": "etims-confirm-transaction-action-modal",
+      "component": "etimsConfirmTransactionActionModal"
+    },
+    {
+      "name": "etims-override-reconciliation-modal",
+      "component": "etimsOverrideReconciliationModal"
+    },
+    {
+      "name":"etims-kra-meta-data-sync-modal",
+      "component":"etimsSyncMetaDataModal"
+    }
+  ],
+  "workspaces2": [
+    {
+      "name": "etims-global-properties-form",
+      "component": "etimsGlobalPropertiesForm",
+      "window": "etims-workspace-window"
+    },
+    {
+      "name": "etims-item-mapping-form",
+      "component": "etimsItemMappingForm",
+      "window": "etims-workspace-window"
+    },
+    {
+      "name": "etims-transaction-details",
+      "component": "etimsTransactionDetails",
+      "window": "etims-workspace-window"
+    },
+    {
+      "name": "etims-credit-note-form",
+      "component": "etimsCreditNoteForm",
+      "window": "etims-workspace-window"
+    }
+  ],
+  "workspaceWindows2": [
+    {
+      "name": "etims-workspace-window",
+      "canMaximize": true,
+      "group": "etims-workspace-group",
+      "width": "wider"
+    }
+  ],
+  "workspaceGroups2": [
+    {
+      "name": "etims-workspace-group",
+      "scopePattern": "/etims",
+      "closeable": true,
+      "overlay": true
+    }
+  ]
+}

package/src/status/etims-status-dashboard.component.tsx

@@ -0,0 +1,212 @@
+import React, { useMemo } from 'react';
+import { Button, InlineLoading, Layer, SkeletonPlaceholder, Tag, Tile } from '@carbon/react';
+import { Renew } from '@carbon/react/icons';
+import { ErrorState, formatDatetime, parseDate, UserHasAccess } from '@openmrs/esm-framework';
+import { useTranslation } from 'react-i18next';
+import Header from '../components/header/header.component';
+import { useEtimsStatus } from './etims-status.resource';
+import type { EtimsStatus, EtimsSyncState } from './etims-status.types';
+import styles from './etims-status-dashboard.scss';
+
+type StatusTagType = 'green' | 'red' | 'gray';
+
+type StatusCard = {
+  key: string;
+  label: string;
+  value: string;
+  tagType: StatusTagType;
+  meta?: string | null;
+};
+
+const formatNullableDatetime = (value?: string | null) => {
+  if (!value) {
+    return '--';
+  }
+
+  try {
+    return formatDatetime(parseDate(value), { mode: 'standard', noToday: true });
+  } catch {
+    return value;
+  }
+};
+
+const displayValue = (value?: string | number | null) => {
+  if (value === null || value === undefined || value === '') {
+    return '--';
+  }
+
+  return String(value);
+};
+
+const StatusMetricCard: React.FC<StatusCard> = ({ label, value, tagType, meta }) => (
+  <Layer>
+    <Tile className={styles.tile}>
+      <div className={styles.tileHeader}>
+        <span className={styles.tileLabel}>{label}</span>
+      </div>
+      <Tag type={tagType} size="md">
+        {value}
+      </Tag>
+      {meta ? <p className={styles.tileMeta}>{meta}</p> : null}
+    </Tile>
+  </Layer>
+);
+
+const DetailRow: React.FC<{ label: string; value: React.ReactNode }> = ({ label, value }) => (
+  <div className={styles.detailRow}>
+    <span className={styles.detailLabel}>{label}</span>
+    <span className={styles.detailValue}>{value}</span>
+  </div>
+);
+
+const SyncStatusPanel: React.FC<{ title: string; sync: EtimsSyncState | null }> = ({ title, sync }) => {
+  const { t } = useTranslation();
+  const hasFailure = Boolean(sync?.lastFailureAt || sync?.lastFailureMessage);
+
+  return (
+    <section className={styles.panel}>
+      <div className={styles.tileHeader}>
+        <h3 className={styles.panelTitle}>{title}</h3>
+        <Tag type={hasFailure ? 'red' : 'green'} size="sm">
+          {hasFailure ? t('syncHasFailures', 'Needs attention') : t('syncHealthy', 'Healthy')}
+        </Tag>
+      </div>
+      <div className={styles.detailList}>
+        <DetailRow label={t('syncCategory', 'Category')} value={displayValue(sync?.syncCategory)} />
+        <DetailRow
+          label={t('lastRequestDatetime', 'Last request')}
+          value={formatNullableDatetime(sync?.lastRequestDatetime)}
+        />
+        <DetailRow label={t('lastSuccessAt', 'Last success')} value={formatNullableDatetime(sync?.lastSuccessAt)} />
+        <DetailRow label={t('lastFailureAt', 'Last failure')} value={formatNullableDatetime(sync?.lastFailureAt)} />
+        <DetailRow label={t('lastRecordCount', 'Last record count')} value={displayValue(sync?.lastRecordCount)} />
+        <DetailRow
+          label={t('lastFailureMessage', 'Last failure message')}
+          value={displayValue(sync?.lastFailureMessage)}
+        />
+      </div>
+    </section>
+  );
+};
+
+const buildStatusCards = (status: EtimsStatus, t: (key: string, fallback: string) => string): StatusCard[] => [
+  {
+    key: 'enabled',
+    label: t('etimsEnabled', 'eTIMS enabled'),
+    value: status.enabled ? t('yes', 'Yes') : t('no', 'No'),
+    tagType: status.enabled ? 'green' : 'gray',
+  },
+  {
+    key: 'gateway',
+    label: t('gatewayHealth', 'Gateway health'),
+    value: status.gatewayHealthy ? t('healthy', 'Healthy') : t('unhealthy', 'Unhealthy'),
+    tagType: status.gatewayHealthy ? 'green' : 'red',
+  },
+  {
+    key: 'licence',
+    label: t('licenceStatus', 'Licence'),
+    value: status.licence?.valid ? t('valid', 'Valid') : t('invalid', 'Invalid'),
+    tagType: status.licence?.valid ? 'green' : 'red',
+    meta: status.licence?.resultMessage,
+  },
+  {
+    key: 'apiKey',
+    label: t('apiKeyConfigured', 'API key configured'),
+    value: status.apiKeyConfigured ? t('yes', 'Yes') : t('no', 'No'),
+    tagType: status.apiKeyConfigured ? 'green' : 'red',
+  },
+];
+
+const EtimsStatusContent: React.FC = () => {
+  const { t } = useTranslation();
+  const { status, error, isLoading, isValidating, mutate } = useEtimsStatus();
+
+  const cards = useMemo(() => (status ? buildStatusCards(status, t) : []), [status, t]);
+
+  if (isLoading) {
+    return (
+      <div className={styles.dashboard}>
+        <InlineLoading status="active" description={t('loadingEtimsStatus', 'Loading eTIMS status...')} />
+        <div className={styles.cardsRow}>
+          {Array.from({ length: 4 }).map((_, index) => (
+            <SkeletonPlaceholder key={index} style={{ width: '100%', height: '7.5rem' }} />
+          ))}
+        </div>
+      </div>
+    );
+  }
+
+  if (error || !status) {
+    return (
+      <div className={styles.dashboard}>
+        <ErrorState error={error} headerTitle={t('etimsStatus', 'eTIMS status')} />
+      </div>
+    );
+  }
+
+  return (
+    <div className={styles.dashboard}>
+      <div className={styles.sectionHeader}>
+        <h2 className={styles.sectionTitle}>{t('connectionOverview', 'Connection overview')}</h2>
+        <Button
+          kind="ghost"
+          size="sm"
+          renderIcon={Renew}
+          onClick={() => mutate()}
+          disabled={isValidating}
+          iconDescription={t('refreshStatus', 'Refresh status')}>
+          {isValidating ? t('refreshing', 'Refreshing...') : t('refreshStatus', 'Refresh status')}
+        </Button>
+      </div>
+
+      <div className={styles.cardsRow}>
+        {cards.map((card) => (
+          <StatusMetricCard {...card} />
+        ))}
+      </div>
+
+      <section className={styles.panel}>
+        <h3 className={styles.panelTitle}>{t('configuration', 'Configuration')}</h3>
+        <div className={styles.detailList}>
+          <DetailRow label={t('environment', 'Environment')} value={displayValue(status.environment)} />
+          <DetailRow label={t('baseUrl', 'Base URL')} value={displayValue(status.baseUrl)} />
+          <DetailRow label={t('businessPin', 'Business PIN')} value={displayValue(status.businessPin)} />
+          <DetailRow label={t('branchId', 'Branch ID')} value={displayValue(status.branchId)} />
+          <DetailRow label={t('contractVersion', 'Contract version')} value={displayValue(status.contractVersion)} />
+          <DetailRow
+            label={t('sandboxValidatedContractVersion', 'Sandbox validated contract version')}
+            value={displayValue(status.sandboxValidatedContractVersion)}
+          />
+          <DetailRow
+            label={t('licenceResultCode', 'Licence result code')}
+            value={displayValue(status.licence?.resultCode)}
+          />
+        </div>
+      </section>
+
+      <div className={styles.sectionHeader}>
+        <h2 className={styles.sectionTitle}>{t('referenceDataSync', 'Reference data sync')}</h2>
+      </div>
+
+      <div className={styles.panelsRow}>
+        <SyncStatusPanel title={t('codeListSync', 'Code list sync')} sync={status.codeListSync} />
+        <SyncStatusPanel title={t('classListSync', 'Class list sync')} sync={status.classListSync} />
+      </div>
+    </div>
+  );
+};
+
+const EtimsStatusDashboard: React.FC = () => {
+  const { t } = useTranslation();
+
+  return (
+    <>
+      <Header title={t('etimsStatus', 'eTIMS status')} />
+      <UserHasAccess privilege="Manage eTIMS Configuration">
+        <EtimsStatusContent />
+      </UserHasAccess>
+    </>
+  );
+};
+
+export default EtimsStatusDashboard;

package/src/status/etims-status-dashboard.scss

@@ -0,0 +1,116 @@
+@use '@carbon/colors';
+@use '@carbon/layout';
+@use '@carbon/type';
+
+.dashboard {
+  display: flex;
+  flex-direction: column;
+  gap: layout.$spacing-05;
+  padding: layout.$spacing-05;
+}
+
+.sectionHeader {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: layout.$spacing-03;
+}
+
+.sectionTitle {
+  @include type.type-style('heading-compact-02');
+  color: colors.$gray-100;
+  margin: 0;
+}
+
+.cardsRow {
+  display: grid;
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+  gap: layout.$spacing-05;
+}
+
+.tile {
+  border: 1px solid colors.$gray-20;
+  min-height: calc(#{layout.$spacing-12} + #{layout.$spacing-06});
+}
+
+.tileHeader {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: layout.$spacing-03;
+  margin-bottom: layout.$spacing-03;
+}
+
+.tileLabel {
+  @include type.type-style('heading-compact-01');
+  color: colors.$gray-70;
+}
+
+.tileMeta {
+  @include type.type-style('helper-text-01');
+  color: colors.$gray-70;
+  margin-top: layout.$spacing-03;
+}
+
+.panelsRow {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: layout.$spacing-05;
+}
+
+.panel {
+  border: 1px solid colors.$gray-20;
+  background: colors.$white;
+  padding: layout.$spacing-05;
+}
+
+.panelTitle {
+  @include type.type-style('heading-compact-01');
+  color: colors.$gray-100;
+  margin: 0 0 layout.$spacing-04;
+}
+
+.detailList {
+  display: flex;
+  flex-direction: column;
+  gap: layout.$spacing-03;
+}
+
+.detailRow {
+  display: grid;
+  grid-template-columns: minmax(#{layout.$spacing-13}, 40%) 1fr;
+  gap: layout.$spacing-03;
+  align-items: start;
+}
+
+.detailLabel {
+  @include type.type-style('label-01');
+  color: colors.$gray-70;
+}
+
+.detailValue {
+  @include type.type-style('body-compact-01');
+  color: colors.$gray-100;
+  word-break: break-word;
+}
+
+:global(.omrs-breakpoint-lt-desktop) {
+  .cardsRow {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+
+  .panelsRow {
+    grid-template-columns: 1fr;
+  }
+}
+
+:global(.omrs-breakpoint-lt-tablet) {
+  .cardsRow {
+    grid-template-columns: 1fr;
+  }
+
+  .detailRow {
+    grid-template-columns: 1fr;
+    gap: layout.$spacing-01;
+  }
+}

package/src/status/etims-status.resource.ts

@@ -0,0 +1,20 @@
+import { type FetchResponse, openmrsFetch, restBaseUrl } from '@openmrs/esm-framework';
+import useSWR from 'swr';
+import type { EtimsStatus } from './etims-status.types';
+
+export const etimsStatusUrl = `${restBaseUrl}/cashier/etimsStatus`;
+
+export const useEtimsStatus = () => {
+  const { data, error, isLoading, isValidating, mutate } = useSWR<FetchResponse<EtimsStatus>>(
+    etimsStatusUrl,
+    openmrsFetch,
+  );
+
+  return {
+    status: data?.data ?? null,
+    error,
+    isLoading,
+    isValidating,
+    mutate,
+  };
+};

package/src/status/etims-status.types.ts

@@ -0,0 +1,30 @@
+export interface EtimsLicenceStatus {
+  valid: boolean;
+  resultCode: string | null;
+  resultMessage: string | null;
+}
+
+export interface EtimsSyncState {
+  uuid: string | null;
+  syncCategory: string | null;
+  lastRequestDatetime: string | null;
+  lastSuccessAt: string | null;
+  lastFailureAt: string | null;
+  lastRecordCount: number | null;
+  lastFailureMessage: string | null;
+}
+
+export interface EtimsStatus {
+  enabled: boolean;
+  environment: string | null;
+  baseUrl: string | null;
+  businessPin: string | null;
+  branchId: string | null;
+  apiKeyConfigured: boolean;
+  contractVersion: string | null;
+  sandboxValidatedContractVersion: string | null;
+  gatewayHealthy: boolean;
+  licence: EtimsLicenceStatus | null;
+  codeListSync: EtimsSyncState | null;
+  classListSync: EtimsSyncState | null;
+}

package/src/transaction/confirm-transaction-action.modal.tsx

@@ -0,0 +1,113 @@
+import React, { useState } from 'react';
+import { Button, InlineLoading } from '@carbon/react';
+import { showSnackbar } from '@openmrs/esm-framework';
+import { useTranslation } from 'react-i18next';
+import {
+  reactivateEtimsTransaction,
+  reconcileEtimsTransaction,
+  retryEtimsTransaction,
+} from './etims-transaction.resource';
+
+type ConfirmTransactionAction = 'retry' | 'reconcile' | 'reactivate';
+
+type ConfirmTransactionActionModalProps = {
+  close: () => void;
+  action: ConfirmTransactionAction;
+  uuid: string;
+  displayName: string;
+  onComplete: () => void;
+};
+
+const ConfirmTransactionActionModal: React.FC<ConfirmTransactionActionModalProps> = ({
+  close,
+  action,
+  uuid,
+  displayName,
+  onComplete,
+}) => {
+  const { t } = useTranslation();
+  const [isSubmitting, setIsSubmitting] = useState(false);
+
+  const copy = {
+    retry: {
+      heading: t('retrySubmission', 'Retry submission'),
+      message: t(
+        'retrySubmissionConfirmation',
+        'Run one submission attempt for "{{displayName}}" using the frozen payload. Inconclusive gateway results stay in reconciliation required.',
+        { displayName },
+      ),
+      successTitle: t('retryComplete', 'Retry complete'),
+      errorTitle: t('retryError', 'Unable to retry transaction'),
+      run: () => retryEtimsTransaction(uuid),
+    },
+    reactivate: {
+      heading: t('reactivateSubmission', 'Retry submission'),
+      message: t(
+        'reactivateSubmissionConfirmation',
+        'Rebuild "{{displayName}}" from the bill\'s current configuration and item mappings, then attempt submission. Fix the blocking mapping or configuration first; if gaps remain it stays in action required. The bill amounts must be unchanged.',
+        { displayName },
+      ),
+      successTitle: t('retryComplete', 'Retry complete'),
+      errorTitle: t('reactivateError', 'Unable to reactivate transaction'),
+      run: () => reactivateEtimsTransaction(uuid),
+    },
+    reconcile: {
+      heading: t('reconcileWithKra', 'Reconcile with KRA'),
+      message: t(
+        'reconcileWithKraConfirmation',
+        'Look up "{{displayName}}" on the eTIMS gateway and update the local transaction from that result. This does not resubmit the invoice.',
+        { displayName },
+      ),
+      successTitle: t('reconciliationComplete', 'Reconciliation complete'),
+      errorTitle: t('reconciliationError', 'Unable to reconcile transaction'),
+      run: () => reconcileEtimsTransaction(uuid),
+    },
+  }[action];
+
+  const heading = copy.heading;
+  const message = copy.message;
+
+  const handleSubmit = async () => {
+    setIsSubmitting(true);
+    try {
+      const result = await copy.run();
+      showSnackbar({
+        kind: 'success',
+        title: copy.successTitle,
+        subtitle:
+          result.resultMessage ?? t('transactionStatusUpdated', 'Status: {{status}}', { status: result.status }),
+      });
+      onComplete();
+      close();
+    } catch (error: any) {
+      showSnackbar({
+        kind: 'error',
+        title: copy.errorTitle,
+        subtitle: error?.message,
+      });
+    } finally {
+      setIsSubmitting(false);
+    }
+  };
+
+  return (
+    <>
+      <div className="cds--modal-header">
+        <h3 className="cds--modal-header__heading">{heading}</h3>
+      </div>
+      <div className="cds--modal-content">
+        <p>{message}</p>
+      </div>
+      <div className="cds--modal-footer">
+        <Button kind="secondary" onClick={close} disabled={isSubmitting}>
+          {t('cancel', 'Cancel')}
+        </Button>
+        <Button kind="primary" onClick={handleSubmit} disabled={isSubmitting}>
+          {isSubmitting ? <InlineLoading description={t('working', 'Working...')} /> : heading}
+        </Button>
+      </div>
+    </>
+  );
+};
+
+export default ConfirmTransactionActionModal;

package/src/transaction/etims-transaction-dashboard.component.tsx

@@ -0,0 +1,23 @@
+import React from 'react';
+import { UserHasAccess } from '@openmrs/esm-framework';
+import { useTranslation } from 'react-i18next';
+import Header from '../components/header/header.component';
+import EtimsTransactionTable from './etims-transaction-table.component';
+import styles from './etims-transaction-dashboard.scss';
+
+const EtimsTransactionDashboard: React.FC = () => {
+  const { t } = useTranslation();
+
+  return (
+    <div>
+      <Header title={t('transactions', 'Transactions')} />
+      <UserHasAccess privilege="View eTIMS Transactions">
+        <div className={styles.dashboard}>
+          <EtimsTransactionTable />
+        </div>
+      </UserHasAccess>
+    </div>
+  );
+};
+
+export default EtimsTransactionDashboard;

package/src/transaction/etims-transaction-dashboard.scss

@@ -0,0 +1,8 @@
+@use '@carbon/layout';
+
+.dashboard {
+  display: flex;
+  flex-direction: column;
+  gap: layout.$spacing-05;
+  padding: layout.$spacing-05;
+}