BUILD YOUR CONNECTOR4 of 8

Build your Connector

Implement your connector logic, data mappings and workflows using the Mediloop Connector SDK.

Create

Project structure

Configure

Build

Test

Go live

A connector is made of capabilities, handlers and mappings. The SDK takes care of plumbing, retries and audit — you focus on business logic.

Define capabilities

typescriptCopy

export default defineCapabilities({
 version: '1.0.0',
 name: 'Acme EHR Connector',
 capabilities: [
  { resource: 'Patient', operations: ['read','write','search'] },
  { resource: 'Observation', operations: ['read','write','search'] }
 ]
});

Implement handlers

typescriptCopy

export const readPatient = read.Handler(async (ctx) => {
 const { client, query } = ctx;
 const data = await client.get('/patients', { params: query });
 return { resourceType: 'Bundle', entry: data.items.map(mapEhrPatientToFhir) };
});

Data mappings & transformations

Source	Target (FHIR Patient)
patient_id	Patient.identifier
first_name	Patient.name[0].given[0]
last_name	Patient.name[0].family
gender_code	Patient.gender
dob	Patient.birthDate
phone	Patient.telecom (phone)

4. Workflows & events

Initial sync — import existing data in batches

Incremental sync — track and sync only changes

Real-time events — handle webhooks / change feeds

Scheduled jobs — run periodic tasks

yamlCopy

triggers:
 - type: webhook
   event: patient.created
   handler: patientCreated
 - type: schedule
   cron: '0 0/15 * * * *'
workflows:
 patientCreated:
  steps: [map, upsert, publishEvent]

5. SDK helpers

HTTP Client

Resilient HTTP client with retries, backoff and timeouts.

Logging

Structured logging with correlation IDs.

Pagination

Cursor and offset pagination helpers.

Audit & metrics

Automatic audit logs and metrics.

Error handling

Standard error types and mappings.

Validation

Validate FHIR resources and payloads.

Best practices

Keep handlers small and focused on a single operation

Use idempotent write operations when possible

Preserve source identifiers and version information

Validate and sanitize all external data

Log meaningful context and correlation IDs

Use mappings to keep transformations maintainable