> ## Documentation Index
> Fetch the complete documentation index at: https://omniloy.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Clinical workflow automation

> Clinical documentation automation and integration with EHR/HIS systems

SofIA SDK enables automation of clinical documentation workflows, from information capture during consultations to structured report generation. This guide explains how automation works and how to integrate it effectively.

## Automation architecture

### Automatic generation workflow

<Steps>
  <Step title="Interaction">
    The healthcare professional interacts with the **SofIA SDK** via voice or text during the consultation.
  </Step>

  <Step title="Transcription and context">
    The SDK captures the conversation and sends it along with patient context to the **Cognitive Framework**.
  </Step>

  <Step title="AI processing">
    **Specialized agents** process the information, generating structured clinical documentation.
  </Step>

  <Step title="Report delivery">
    The structured report is returned to the SDK, which delivers it to the **EHR/HIS** via the `handleReport` callback.
  </Step>
</Steps>

### System components

* **Data capture**: Audio transcription and patient contextual data
* **Intelligent processing**: Cognitive framework with specialized agents
* **Structured generation**: Reports conforming to predefined JSON schemas
* **Automatic integration**: Data delivery through callbacks for persistence

## Types of automation

### Automatic document generation

SofIA automatically generates structured clinical documentation based on:

* **Consultation transcription**: Real-time processed doctor-patient conversation
* **Patient contextual data**: Information provided in `patientdata`
* **Predefined schema**: Structure defined in `template` that specifies what information to generate
* **Automatic validation**: Clinical coherence verification before report delivery

### Structured report integration

SofIA's automation focuses on **report generation** from consultation transcripts. The SDK generates structured JSON reports matching your template schema, which your application can then use to populate forms, update EHR fields, or create clinical documents.

SofIA uses specialized AI agents for documentation generation and quality review.

## Automation configuration

### Required properties for automation

To enable automation, SofIA SDK requires:

* **`template`**: JSON schema that defines what information to generate and how to structure it
* **`handleReport`**: Callback function that receives the generated report
* **`userid` and `patientid`**: Identifiers for traceability and context
* **`patientdata`** (optional): Patient contextual information to enrich generation

### Complete automation example

```html theme={null}
<sofia-sdk
  id="sofia"
  apikey="your-api-key"
  userid="dr-smith-789"
  patientid="patient-123"
  templateid="soap-general-v1"
  template='{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "SOAP Note",
    "type": "object",
    "properties": {
      "subjective": { "type": "string", "description": "Patient reported symptoms" },
      "objective": { "type": "string", "description": "Clinical examination findings" },
      "assessment": { "type": "string", "description": "Diagnosis" },
      "plan": { "type": "string", "description": "Treatment plan" }
    },
    "required": ["subjective", "assessment"]
  }'
  patientdata='{"fullName":"Jane Doe","birthDate":"1985-05-15","extraData":{"medical_practice":"Internal Medicine"}}'
></sofia-sdk>

<script>
// Assign handleReport as an element property once the component is defined
customElements.whenDefined('sofia-sdk').then(() => {
  const sofia = document.getElementById('sofia');
  sofia.handleReport = (report) => {
    console.log('Report received:', report);
    // Send to your EHR/HIS system
    fetch('/api/clinical-reports', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        patientId: 'patient-123',
        report: report,
        generatedAt: new Date().toISOString()
      })
    });
  };
});
</script>
```

### handleReport callback operation

The `handleReport` callback is the main integration point:

* **Data reception**: Receives structured report according to defined schema
* **JSON format**: Data arrives in validated JSON format
* **Execution timing**: Executes when user requests documentation generation
* **Persistence responsibility**: Callback must manage saving in EHR/HIS system

## Implementation best practices

### Schema design

* Define fields relevant to the specific consultation type
* Provide detailed `description` values for each field to guide AI extraction
* Enable clinical coding either by setting your custom field's `source` **or** by requesting the terminology directly in the field `description` (e.g. "provide the diagnosis with its ICD-10 code") — see [Clinical data schemas](/sofia/en/sdk/templates#clinical-coding-sources)
* Include `required` only for fields that are essential to every consultation

### Integration management

* Validate structure and content of received reports before persisting
* Implement error handling for network or save failures
* Maintain audit records of who generated what and when
* Control schema versions for backward compatibility

### Quality considerations

* Establish professional review processes for generated documentation
* Start with partial automation and increase scope gradually
* Use feedback to refine schemas and improve output quality

## Limitations and considerations

### Technical limitations

* **Schema dependency**: Automation quality depends on JSON schema design
* **Available context**: Generation is based on information available during consultation
* **Audio processing**: Requires sufficient audio quality for accurate transcription
* **Connectivity**: Needs stable connection for real-time processing

### Professional and legal responsibilities

* The healthcare professional maintains responsibility for all generated content and clinical decisions
* Review and validate information before final persistence in your EHR/HIS
* Ensure patient consent for AI-assisted documentation per applicable regulations
* Maintain traceability records for compliance audits

## Next steps

* **[Clinical chat](/sofia/en/sdk/chat)**: Use the conversational assistant to complement automation
* **[Clinical data schemas](/sofia/en/sdk/templates)**: Design effective schemas for your practice
* **[Error Reference](/sofia/en/sdk/error-reference)**: Handle errors in automated workflows