Complete Guide: Middleware Bridging for Legacy System Integration in Healthcare Facilities

In the era of digitalization of health services, healthcare facilities (fasyankes) such as hospitals and clinics are faced with increasingly high demands for data integration. Hospital Management Information Systems (SIMRS) or Clinic Management Information Systems (SIM Klinik) that have been operating for years are often built with technologies and architectures that do not support modern interoperability standards such as FHIR (Fast Healthcare Interoperability Resources) R4 or HL7 v2.5.1. This challenge becomes even more real with the mandatory integration into national platforms such as BPJS Kesehatan or SatuSehat. For example, a hospital with a Delphi- or Visual FoxPro-based SIMRS from the 2000s must be able to send patient data in real-time to SatuSehat, which, notably, requires the FHIR R4 JSON format via RESTful API. Without a strong bridge, integration efforts will take time, cost, and be prone to failure. This article will guide you step by step in designing and implementing a robust and efficient middleware bridging, enabling your legacy system to "speak" with the modern digital health ecosystem, minimizing operational disruption, and maximizing the value of existing technology investments.

Basic Concepts of Middleware Bridging for Health Systems

Middleware bridging is an intermediary software layer that acts as a translator and connector between two or more systems that were not designed to communicate directly. In the context of legacy systems in healthcare facilities, this middleware becomes crucial because old systems often have unique characteristics such as proprietary databases (e.g., dBase, FoxPro DBF), non-standard APIs (e.g., legacy SOAP or RPC), or even no API at all, thus requiring direct database access. The main function of middleware bridging is to overcome differences in communication protocols, data formats, and information semantics. For example, an old SIMRS may store patient data in a table with column names 'No_MedRek' and 'Nama_Lengkap', while the FHIR R4 standard requires 'Patient.identifier' and 'Patient.name.text'. The middleware will map, transform, and validate this data before forwarding it.

The importance of this middleware also lies in its ability to isolate legacy systems from the complexity of external integration. Rather than modifying the core system, which is high-risk and expensive, middleware allows healthcare facilities to maintain the stability of old systems while still meeting new integration requirements. It also provides a single centralized control point for all integrations, facilitating monitoring, logging, error handling, and security. For example, all authentication to BPJS or SatuSehat can be managed in the middleware, not in every SIMRS module. This approach also enables gradual evolution; when the legacy system is eventually replaced, the middleware can be adjusted to interact with the new system without disrupting existing external integrations.

Architecturally, middleware bridging can be implemented as a microservice or a separate monolithic application running on a dedicated server. The choice of architecture depends on the scale of needs, integration complexity, and available IT resources. For medium to large healthcare facilities, a microservice approach using containerization (Docker, Kubernetes) will provide better flexibility and scalability. However, for small healthcare facilities with limited integration, a simple monolithic application built with a framework such as Laravel or Node.js Express may be sufficient. The key to success lies in a modular design, the ability to manage various connectors (database, REST API, SOAP), and reliability in processing data transactions asynchronously to avoid bottlenecks.

In addition, middleware can also function as a workflow orchestrator. For example, when a patient registers at SIMRS, the middleware can automatically trigger a series of actions: retrieving data from SIMRS, converting it to the FHIR Patient format, sending it to SatuSehat, waiting for a response, and then updating the status in SIMRS. This reduces manual workload and the risk of errors. The ability to manage message queues is also very important, especially when dealing with external APIs that have rate limiting or are often unstable. With a queue (such as RabbitMQ or Apache Kafka), the middleware can store messages that failed to send and retry them automatically, ensuring data resilience.

Implementation Details and Technology Selection

In building middleware bridging, selecting the right technology stack is the foundation of success. For legacy system integration cases in healthcare facilities, we recommend a combination of technologies that have proven stable, have a broad ecosystem, and support rapid development. As the main backend, PHP with the Laravel version 11.x framework is an excellent choice, supported by PHP 8.3. Laravel provides a rich ecosystem for building RESTful APIs, authentication (sanctum, passport), queueing (with Redis or RabbitMQ), and ORM (Eloquent) that simplifies interaction with various types of databases. A relational database such as PostgreSQL 16 will be a robust and scalable choice for storing transaction logs, integration statuses, and master data that may be needed by the middleware itself.

For cases where lighter real-time data processing or complex data transformation is required, Node.js 20 LTS with the Express.js framework can be used as a separate microservice. For example, a Node.js service can function specifically for parsing HL7 v2.5.1 MSH segment or for validating FHIR R4 schemas. Integration with healthcare standards such as FHIR R4 (for example, using the HAPI FHIR library if using Java, or a custom parser/validator in Node.js/PHP) and HL7 v2.5.1 is essential. Middleware must be able to produce FHIR R4 JSON payloads for SatuSehat or process HL7 v2 messages from legacy systems. For communication between microservices or with queuing systems, Redis can be utilized as a simple message broker or as a cache for external API access tokens.

Security aspects cannot be ignored. Middleware must implement strong authentication and authorization. For external APIs such as BPJS or SatuSehat, the use of OAuth2 or strictly managed API Keys is the standard. Ensure all communications use HTTPS/TLS 1.2 or above. For internal communication with legacy systems, if possible, use encrypted connections. All sensitive credentials must be stored securely, for example using environment variables or HashiCorp Vault. Logging and monitoring systems must also be implemented comprehensively. Use services such as Sentry for error tracking and Prometheus/Grafana for monitoring middleware performance metrics, such as transactions per minute, latency, and success/failure rates.

The integration process with legacy databases can be a challenge in itself. If the legacy system does not have an API, middleware needs to connect directly to the database. This may require a special driver (for example, ODBC for dBase/FoxPro) or a non-standard database connector. Make sure to do this with read-only access rights to minimize risk to the core data of the legacy system. For writing back to the legacy system (for example, updating status after successful integration), it is recommended to use the API provided by the legacy system if available, or to create a controlled and tested writing mechanism, for example through existing stored procedures or triggers in the legacy database.

Version control for middleware code must use Git, and the deployment process must be automated using a CI/CD pipeline (for example, GitLab CI/CD, GitHub Actions). This ensures consistency, reduces manual errors, and accelerates the development cycle. Testing (unit testing, integration testing) is a vital component to ensure the quality and reliability of middleware. With Laravel, PHPUnit makes it easy to write unit tests. Make sure to test positive, negative, and edge cases such as empty data, incorrect format, or unexpected API responses.

Example of Middleware Implementation Code

Here is a simple implementation example in Laravel 11.x to receive patient data from a legacy system and forward it to SatuSehat, as well as an example of data transformation using Node.js.

1. Laravel Controller to Receive and Forward Patient Data

This is an example of a Laravel controller that will receive patient data from a legacy system (for example, via a custom REST API endpoint from an old SIMRS) and then call a service to process and send it to SatuSehat. Assume there is a `PatientService` that handles business logic and external integration.

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use App\Services\PatientService;
use Illuminate\Support\Facades\Log;
use Illuminate\Validation\ValidationException;

class PatientBridgeController extends Controller
{
    protected $patientService;

    public function __construct(PatientService $patientService)
    {
        $this->patientService = $patientService;
    }

    /**
     * Menerima data pasien dari sistem legacy dan meneruskannya ke SatuSehat.
     * @param Request $request
     * @return \Illuminate\Http\JsonResponse
     */
    public function receivePatientData(Request $request)
    {
        Log::info('Menerima permintaan data pasien dari legacy system.', ['payload' => $request->all()]);
        try {
            $validatedData = $request->validate([
                'no_rm_legacy' => 'required|string|max:50',
                'nama_lengkap' => 'required|string|max:255',
                'tanggal_lahir' => 'required|date',
                'jenis_kelamin' => 'required|in:L,P',
                'nik' => 'nullable|string|max:16',
                'alamat' => 'nullable|string|max:255'
            ]);

            // Memanggil service untuk memproses dan mengirim ke SatuSehat
            $result = $this->patientService->processAndSendToSatuSehat($validatedData);

            if ($result['success']) {
                Log::info('Data pasien berhasil diproses dan dikirim ke SatuSehat.', ['satu_sehat_id' => $result['satu_sehat_id']]);
                return response()->json(['message' => 'Data pasien berhasil diproses', 'satu_sehat_id' => $result['satu_sehat_id']], 200);
            } else {
                Log::error('Gagal mengirim data pasien ke SatuSehat.', ['error' => $result['error']]);
                return response()->json(['message' => 'Gagal memproses data pasien', 'error' => $result['error']], 500);
            }
        } catch (ValidationException $e) {
            Log::warning('Validasi data pasien gagal.', ['errors' => $e->errors()]);
            return response()->json(['message' => 'Data tidak valid', 'errors' => $e->errors()], 422);
        } catch (\Exception $e) {
            Log::error('Terjadi kesalahan tak terduga saat memproses data pasien.', ['exception' => $e->getMessage()]);
            return response()->json(['message' => 'Terjadi kesalahan internal server', 'error' => $e->getMessage()], 500);
        }
    }
}

Code Explanation 1: Controller `PatientBridgeController` is responsible for receiving POST requests from the legacy system. It performs basic data validation using Laravel's validation features. After validation, the request is forwarded to `PatientService` for more complex business logic, such as data transformation and interaction with the SatuSehat API. The use of `Log::info` and `Log::error` is very important for audit trail and debugging. Handling `ValidationException` and generic `Exception` ensures informative responses to the sender and proper error logging.

2. Node.js Script for Data Transformation to FHIR R4 JSON

The following is an example of a Node.js function that takes data from a legacy format (for example, the one received from Laravel) and converts it into the FHIR R4 Patient JSON format suitable for SatuSehat.

// patientTransformer.js

/**
 * Mengubah data pasien dari format legacy ke FHIR R4 Patient JSON.
 * @param {object} legacyPatientData - Data pasien dari sistem legacy.
 * @returns {object} FHIR R4 Patient Resource JSON.
 */
function transformToFhirPatient(legacyPatientData) {
    const genderMap = {
        'L': 'male',
        'P': 'female'
    };

    const birthDate = new Date(legacyPatientData.tanggal_lahir);
    const fhirPatient = {
        resourceType: "Patient",
        identifier: [],
        name: [{
            use: "official",
            text: legacyPatientData.nama_lengkap
        }],
        gender: genderMap[legacyPatientData.jenis_kelamin] || 'unknown',
        birthDate: birthDate.toISOString().split('T')[0] // Format YYYY-MM-DD
    };

    if (legacyPatientData.no_rm_legacy) {
        fhirPatient.identifier.push({
            use: "usual",
            type: {
                coding: [{
                    system: "http://terminology.hl7.org/CodeSystem/v2-0203",
                    code: "MR"
                }],
                text: "Medical Record Number"
            },
            system: "urn:oid:1.2.36.1.2001.1005.17", // Contoh OID untuk sistem internal
            value: legacyPatientData.no_rm_legacy
        });
    }

    if (legacyPatientData.nik) {
        fhirPatient.identifier.push({
            use: "official",
            type: {
                coding: [{
                    system: "http://terminology.hl7.org/CodeSystem/v2-0203",
                    code: "NI"
                }],
                text: "National Identity Number"
            },
            system: "https://satusehat.kemkes.go.id/fhir/v1/identifier/nik",
            value: legacyPatientData.nik
        });
    }

    if (legacyPatientData.alamat) {
        fhirPatient.address = [{
            use: "home",
            text: legacyPatientData.alamat
        }];
    }

    return fhirPatient;
}

module.exports = { transformToFhirPatient };

Code Explanation 2: This `transformToFhirPatient` function receives a `legacyPatientData` object that has been validated by Laravel. This function then builds a JSON object according to the FHIR R4 specification for the Patient resource. The `genderMap` mapping is a simple example for converting internal gender codes ('L', 'P') to the FHIR standard ('male', 'female'). The `identifier` section conditionally adds the medical record number and NIK if available, using `system` and `code` in accordance with FHIR standards and SatuSehat guidelines. This function can be called from Laravel's `PatientService` via an HTTP request to a Node.js microservice or even run directly if Node.js is embedded (for example, via an `exec` command, although this is not recommended for performance).

Example Payload and Error Handling

This section will present an example of realistic data payload in FHIR R4 JSON format for SatuSehat integration, as well as how middleware can handle common error scenarios.

Example FHIR R4 Patient Payload for SatuSehat

This is an example of patient data that has been transformed by the middleware and is ready to be sent to the SatuSehat API. Note the use of `resourceType`, `identifier` with the appropriate system (for NIK and Medical Record ID), `name`, `gender`, and `birthDate` according to the FHIR R4 Patient specification and the SatuSehat guidelines.

{
    "resourceType": "Patient",
    "identifier": [
        {
            "use": "official",
            "system": "https://satusehat.kemkes.go.id/fhir/v1/identifier/nik",
            "value": "327xxxxxxxxxxxxx"
        },
        {
            "use": "usual",
            "type": {
                "coding": [
                    {
                        "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
                        "code": "MR"
                    }
                ],
                "text": "Medical Record Number"
            },
            "system": "urn:oid:1.2.36.1.2001.1005.17",
            "value": "RM00012345"
        }
    ],
    "name": [
        {
            "use": "official",
            "text": "Budi Santoso"
        }
    ],
    "gender": "male",
    "birthDate": "1985-04-20",
    "address": [
        {
            "use": "home",
            "text": "Jl. Merdeka No. 10, Jakarta Pusat"
        }
    ]
}

Example Error Message and Handling

Middleware must be designed to handle various error responses from external APIs (for example, SatuSehat) or internal failures. The following is an example of an error response from the SatuSehat API and its handling strategy:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "error",
            "code": "invalid",
            "details": {
                "text": "Identifier with system https://satusehat.kemkes.go.id/fhir/v1/identifier/nik and value 327xxxxxxxxxxxxx already exists."
            },
            "expression": [
                "Patient.identifier"
            ]
        }
    ]
}

Error Handling:

1. Identify Error Type: Middleware must parse the HTTP response and JSON payload to identify the status code (for example, 400, 401, 404, 500) and the specific error message in `OperationOutcome`. In the example above, the code `invalid` and the detail `Identifier ... already exists` indicate that a patient with that NIK is already registered in SatuSehat.
2. Detailed Logging: Every error must be logged in detail, including the request payload sent, the complete error response, timestamp, and unique transaction ID. This is crucial for debugging and auditing. Example: `Log::error('SatuSehat API error', ['status' => 400, 'response' => $responseBody, 'payload' => $requestPayload, 'transaction_id' => $uuid]);`.

With such a logging mechanism, the operations team can perform root cause analysis without having to reproduce the incident manually. In addition, middleware should implement a retry mechanism with exponential backoff for transient errors (for example, 429 Too Many Requests or 503 Service Unavailable), while permanent errors such as 400 Bad Request do not need to be retried because the payload is indeed invalid.

To maintain data consistency, error handling results also need to be mapped to the internal statuses of the legacy system. For example, when SatuSehat rejects because of a duplicate NIK, middleware can return the status DUPLICATE_IDENTIFIER to the old system, so that staff at healthcare facilities receive an easily understandable message. In this way, the complexity of the FHIR protocol does not leak into legacy applications that may only recognize text-based message formats or simple database tables.

Practical Tips for Implementing Middleware Bridging in Healthcare Facilities

First, start with the most critical data mapping, not all fields at once. Identify the minimum elements needed for interoperability, such as patient identifier (NIK), name, date of birth, gender, and region code. Create an explicit mapping table between the legacy data structure and FHIR resources, then store it as configuration so it can be easily changed without having to modify program code. This approach facilitates audits and reduces regression risk when there are standard updates from the Ministry of Health.

Second, apply the idempotency principle to every middleware endpoint. Because health integration often involves resending data due to timeouts or network disruptions, the middleware must be able to detect whether a resource has already been sent. Use a unique key such as a combination of NIK and resource type, then store the sending trace in a transaction table. That way, resending will not create duplicate data in SatuSehat or in the legacy system.

Third, prepare observability from the start. In addition to logging, add metrics such as the number of successful requests, the number of errors per status code, and average latency. A simple dashboard that displays these metrics will greatly help the healthcare facility IT team detect anomalies, for example a spike in 401 errors indicating an expired access token or misconfiguration. Do not forget to test in a sandbox environment before go-live, including failure scenarios such as a connection dropping in the middle of a process.

FAQ

Must bridging middleware use a particular programming language?

No. Any programming language can be used as long as it can handle HTTP, JSON, and data transformation well. Common choices in healthcare facility environments are PHP (Laravel), Node.js, Python, or Java. What is more important is support for FHIR libraries, ease of logging, and the availability of IT team resources to maintain it.

What if the legacy system has no API at all?

Middleware can still be built using an adapter approach. If the legacy system only provides database access, the middleware can read and write directly to tables through a controlled repository layer. If only file export-import is available, the middleware can process CSV or XML files on a scheduled basis. The key is to separate integration logic from legacy business logic so that changes on one side do not break the other side.

Is patient data safe when sent through middleware?

Security must be a priority. Use HTTPS for all communication, store credentials and tokens in an encrypted secret manager or environment variable, and apply the least privilege principle to the accounts used. For sensitive data, consider additional encryption at the payload level and ensure logs do not store personal data in full. Regular access audits are also needed to comply with personal data protection regulations.

How long does it take to build this middleware?

For basic integrations such as sending patient and encounter data, the estimate is around 4–8 weeks depending on the complexity of the legacy system and the availability of documentation. However, the greatest time is usually not in writing code, but in data mapping, end-to-end testing, and alignment with healthcare facility policies. Plan gradual iterations so that benefits can be felt sooner.

Conclusion

Bridging middleware is an important bridge that allows legacy systems in healthcare facilities to keep operating while connecting to the digital health ecosystem such as SatuSehat. With a design that pays attention to data mapping, error handling, idempotency, and observability, integration can run stably without disrupting daily services. Investing in good middleware will save long-term maintenance costs and accelerate the digital transformation of healthcare facilities.

If your healthcare facility is planning or facing obstacles in integrating a legacy system into the national platform, our team is ready to help from assessment, architecture design, to implementation and mentoring. Contact us for a free consultation session and get solution recommendations that suit your healthcare facility's needs and operational scale.

This article is part of the education by Nugroho Setiawan, an IT consultant in Jogja. Related solutions: SIMRS Integrator Bridging BPJS & SatuSehat. Need a free consultation?