Diagnostics Component#

The Components API is currently in private beta. If you're interested in participating, please contact us. Changes to the API may occur.

The diagnostics component allows you to embed the diagnostics module into your own application. Inject the clinical notes and/or laboratory results through the embedding code, allowing your users to continue directly from where they left off.

For a complete workflow that demonstrates creating diagnostic cases via the API and then using them with components, see our [**Complete Diagnostic Workflow Tutorial**](/docs/tutorials/api-to-components/) that covers the entire process from case creation to component integration.

Getting started#

If you have already created a diagnostic case using the Cases API, you can simply reference it by its case ID:

POST https://components.gekkovet.com/api/v1/sessions HTTP/1.1
Content-Type: application/json
Authorization: Bearer YOUR_JWT_TOKEN

{
  "component": "diagnostics",
  "case_id": "550e8400-e29b-41d4-a716-446655440000"
}

This approach automatically loads the patient information, clinical notes, and any processed symptoms from the existing case. Additionally, when initialized with a case_id, the component automatically synchronizes all data changes back to the backend case in real-time - you don’t need to manually store data back to the case.

Option 2: Manual Session Creation#

Alternatively, you can create a session by manually providing the diagnostic information:

POST https://components.gekkovet.com/api/v1/sessions HTTP/1.1
Content-Type: application/json
Authorization: Bearer YOUR_JWT_TOKEN

{
  "component": "diagnostics",
  "notes": "Clinical notes go here",
  "attachments": [
    {
      "filename": "my_attachment.pdf",
      "data": "base64 encoded pdf"
    }
  ],
  "patient": {
    "species": "dog",
    "breed": "Labrador Retriever",
    "date_of_birth": "2019-01-01",
    "weight_kg": 20,
    "gender": "female",
    "intact": true
  }
}

Session Response#

Both approaches will return a session response containing a session ID and URL that you can use to embed the diagnostics module into your application:

{ "session_id": "SESSION_ID", "url": "https://components.gekkovet.com/components/diagnostics/SESSION_ID" }

You can then embed the diagnostics module using an iframe or webview:

<iframe src="https://components.gekkovet.com/components/diagnostics/SESSION_ID" width="100%" height="800px"></iframe>

Cross-Frame Communication#

The diagnostics component uses the Window.postMessage API to communicate between the iframe and your application. This allows you to receive real-time updates about user interactions within the component.

To listen for events from the embedded component, add the following code to your application:

// Initialize an array to store messages
const logMessages = [];

// Add event listener for messages from the iframe
window.addEventListener('message', (event) => {
  // Verify the origin for security
  if (!event.origin.startsWith('https://components.gekkovet.com')) {
    return;
  }

  // Process the event data
  const data = JSON.parse(event.data);
  console.log(`${data.timestamp} -- ${data.type} -- ${JSON.stringify(data.payload)}`);

  // Handle different event types
  switch(data.type) {
    case 'init':
      console.log('Diagnostics component initialized');
      break;
    case 'symptomSelected':
      console.log(`Symptom selected: ${data.payload.name}`);
      break;
    // Handle other event types...
  }
});

Event Types#

The diagnostics component emits the following events:

init#

Sent when the component is fully loaded and ready to use.

{
  "type": "init",
  "timestamp": "2025-05-02T10:15:30.123Z",
  "payload": {
    "sessionId": "SESSION_ID",
    "version": "1.0.0"
  }
}

symptomSelected#

Sent when a user selects a symptom in the diagnosis workflow.

{
  "type": "symptomSelected",
  "timestamp": "2025-05-02T10:16:45.789Z",
  "payload": {
    "id": 123,
    "name": "Gastrointestinal signs, Diarrhea, Acute"
  }
}

diagnoseSelected#

Sent when a diagnosis is selected from the list of possible diagnoses.

{
  "type": "diagnoseSelected",
  "timestamp": "2025-05-02T10:18:12.456Z",
  "payload": {
    "id": 456,
    "name": "Acute Gastroenteritis"
  }
}

treatmentSelected#

Sent when a treatment option is selected.

{
  "type": "treatmentSelected",
  "timestamp": "2025-05-02T10:20:05.123Z",
  "payload": {
    "id": 789,
    "name": "..."
  }
}

drugDosageSelected#

Sent when a drug dosage is selected or calculated.

{
  "type": "drugDosageSelected",
  "timestamp": "2025-05-02T10:21:30.789Z",
  "payload": {
    "drugSubstanceId": 101,
    "drugSubstanceName": "..",
    "adiministrationRoute": "...",
    "dosage": {
      "unit": "mg",
      "value": 12
    }
  }
}

soapNotesGenerated#

Sent when SOAP notes are generated based on the diagnostic process.

{
  "type": "soapNotesGenerated",
  "timestamp": "2025-05-02T10:25:45.123Z",
  "payload": {
    "notes": "SOAP notes content goes here"
  }
}

Step Completion Events#

The component emits events when users complete specific workflow steps:

  • stepDiagnosisComplete - Diagnosis step completed
  • stepTreatmentComplete - Treatment selection completed
  • stepDosageComplete - Drug dosage calculation completed

These events follow a similar structure:

{
  "type": "stepDiagnosisComplete",
  "timestamp": "2025-05-02T10:23:10.456Z",
  "payload": {
    "nextStep": "treatment"
  }
}

save#

Sent when the user explicitly saves their work or the component automatically saves progress.

{
  "type": "save",
  "timestamp": "2025-05-02T10:30:15.789Z",
  "payload": {
    "currentStep": "diagnosis",
    "selectedSymptoms": [123, 124, 125],
    "selectedDiagnoses": [456],
    "selectedTreatments": []
  }
}

Complete Workflow Integration#

For a comprehensive example that demonstrates the entire workflow from creating diagnostic cases via the API to integrating them with components, including:

  • Creating and monitoring diagnostic cases using the Cases API
  • Waiting for AI processing to complete
  • Creating component sessions with case IDs
  • Handling cross-frame communication events
  • Syncing component data back to API cases
  • Complete error handling and best practices

Please refer to our Complete Diagnostic Workflow: From API Cases to Components Integration tutorial, which provides a full working example with code samples and implementation guidance.

Security Considerations#

When implementing cross-frame communication, always validate the origin of messages to prevent cross-site scripting attacks:

window.addEventListener('message', (event) => {
  // IMPORTANT: Always verify the sender's origin
  if (!event.origin.startsWith('https://components.gekkovet.com')) {
    console.warn('Received message from untrusted origin:', event.origin);
    return;
  }

  // Process the message...
});

For more information about secure cross-origin communication, refer to the MDN documentation on postMessage security.

Backward Components Drug Dosage Calculator Forward