Swedish Healthcare Service - Health Condition Description - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Deployment and Operations

Deployment and Operations Guide

This guide covers deployment, configuration, and operational procedures for implementing the Health Condition Description services.

Prerequisites

System Requirements

Consumer Systems:

• Java 8+ or .NET Framework 4.5+ (for SOAP/XML processing)
• TLS 1.2+ support
• X.509 certificate capability
• Adequate storage for logs and audit trails

Producer Systems:

• Application server with SOAP/WS-Security support
• Database with suitable capacity
• Integration with Engagement Index
• Monitoring and logging infrastructure

Network Requirements

Firewall Rules:

• Outbound HTTPS (443) to service platform
• Inbound HTTPS (443) for producer services
• Access to HSA catalog services
• Access to engagement index services

Bandwidth:

• Minimum 10 Mbps
• Recommended 100 Mbps for producers

Security Prerequisites

Certificates:

• Valid X.509 certificate for system identity
• Certificate signed by trusted CA
• Private key securely stored
• Certificate chain available

HSA Registration:

• System registered in HSA catalog
• HSA-ID assigned
• Organizational relationships configured

Configuration

Service Consumer Configuration

Endpoint Configuration

Service Platform URLs:

# National Aggregating Service
national.endpoint=https://service-platform.inera.se/clinicalprocess/healthcond/description/GetCareDocumentation/3
national.hsaid=5565594230

# Regional Aggregating Service (example)
regional.endpoint=https://regional-platform.example.se/clinicalprocess/healthcond/description/GetCareDocumentation/3
regional.hsaid=SE2321000016-0000

# Direct Source System (example)
source.endpoint=https://source-system.example.se/clinicalprocess/healthcond/description/GetCareDocumentation/3
source.hsaid=SE2321000016-SYS1

Timeout Configuration

# Connection timeout (milliseconds)
connection.timeout=5000

# Read timeout (milliseconds)
read.timeout=30000

# Aggregator timeout (longer for multiple systems)
aggregator.timeout=60000

Retry Configuration

# Maximum retry attempts
max.retries=3

# Initial retry delay (milliseconds)
retry.delay.initial=1000

# Retry delay multiplier (exponential backoff)
retry.delay.multiplier=2.0

# Maximum retry delay (milliseconds)
retry.delay.max=30000

Certificate Configuration

Java KeyStore Example:

# KeyStore location
keystore.path=/etc/certs/consumer-keystore.jks
keystore.password=${KEYSTORE_PASSWORD}

# TrustStore location
truststore.path=/etc/certs/truststore.jks
truststore.password=${TRUSTSTORE_PASSWORD}

# Certificate alias
cert.alias=consumer-cert-2024

Windows Certificate Store Example:

<configuration>
  <system.serviceModel>
    <client>
      <endpoint>
        <identity>
          <certificateReference findValue="Consumer System 2024"
                                storeName="My"
                                storeLocation="LocalMachine"
                                x509FindType="FindBySubjectName"/>
        </identity>
      </endpoint>
    </client>
  </system.serviceModel>
</configuration>

Service Producer Configuration

Service Exposure

WSDL Location:

https://[producer-domain]/clinicalprocess/healthcond/description/GetCareDocumentation/3?wsdl

Service Binding:

<service name="GetCareDocumentationService">
  <port name="GetCareDocumentationPort" 
        binding="tns:GetCareDocumentationBinding">
    <soap:address location="https://source-system.example.se/GetCareDocumentation/3"/>
    <wsa:Address>https://source-system.example.se/GetCareDocumentation/3</wsa:Address>
  </port>
</service>

Database Configuration

Connection Pool:

# Connection pool size
db.pool.min=10
db.pool.max=100

# Connection timeout
db.connection.timeout=5000

# Query timeout
db.query.timeout=25000

Indexes: Ensure indexes on:

• patient_id
• document_date
• care_unit_id
• document_id

Engagement Index Integration

EI Update Endpoint:

ei.endpoint=https://engagement-index.inera.se/update
ei.hsaid=ENGAGEMENT-INDEX-HSAID
ei.update.batch.size=100
ei.update.interval=60000

Update Trigger Configuration:

-- Trigger to queue EI updates
CREATE TRIGGER ei_update_trigger
AFTER INSERT OR UPDATE ON care_documentation
FOR EACH ROW
BEGIN
  INSERT INTO ei_update_queue (patient_id, domain, action, timestamp)
  VALUES (NEW.patient_id, 'CareDocumentation', 'UPDATE', NOW());
END;

Load Balancer Configuration

Health Check Endpoint:

GET /health
Response: 200 OK

Session Affinity:

• Not required (services are stateless)
• Exception: Partial data retrieval (use session stickiness)

Example nginx Configuration:

upstream care_doc_backend {
    server backend1.example.com:443;
    server backend2.example.com:443;
    
    # Health check
    check interval=10000 rise=2 fall=3 timeout=5000;
}

server {
    listen 443 ssl;
    server_name service-platform.example.se;
    
    ssl_certificate /etc/certs/server.crt;
    ssl_certificate_key /etc/certs/server.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    
    location /clinicalprocess/healthcond/description/ {
        proxy_pass https://care_doc_backend;
        proxy_ssl_verify on;
        proxy_ssl_trusted_certificate /etc/certs/ca-bundle.crt;
        proxy_read_timeout 60s;
    }
}

Certificate Management

Certificate Lifecycle

1. Generation
   • Generate key pair (minimum 2048-bit RSA or equivalent EC)
   • Create certificate signing request (CSR)
   • Submit to approved CA
2. Installation
   • Install certificate in keystore/certificate store
   • Configure application to use certificate
   • Test certificate validation
3. Monitoring
   • Monitor certificate expiration dates
   • Alert 90 days before expiration
   • Plan renewal
4. Renewal
   • Generate new CSR
   • Obtain new certificate
   • Test in non-production
   • Deploy to production
   • Update trust relationships
5. Revocation
   • Revoke compromised certificates immediately
   • Update CRL/OCSP
   • Notify stakeholders

Certificate Requirements

Subject Fields:

CN=System Name
O=Organization Name
C=SE

Key Usage:

• Digital Signature
• Key Encipherment

Extended Key Usage:

• Client Authentication (for consumers)
• Server Authentication (for producers)

Validity:

• Maximum 2 years
• Recommended 1 year

Monitoring

Service Health Metrics

Key Metrics to Monitor:

Logging Requirements

Minimum Log Levels:

• Production: INFO
• Troubleshooting: DEBUG (temporary)

Required Log Entries:

Per Request:

[timestamp] [request-id] [service] [operation] [patient-id] [user-id] [result-code] [duration-ms]

Example:

2024-10-27T14:32:15.123Z REQ-2024-123456 GetCareDocumentation GetCareDocumentation 197001011234 USER-5678 OK 1234

Error Logging:

[timestamp] [request-id] [ERROR] [error-code] [message] [stack-trace]

Monitoring Tools Integration

Prometheus Metrics:

# Service availability
service_up{service="GetCareDocumentation"} 1

# Request duration histogram
service_request_duration_seconds{service="GetCareDocumentation",quantile="0.95"} 5.2

# Error counter
service_errors_total{service="GetCareDocumentation",error_code="TIMEOUT"} 12

Example Prometheus Configuration:

scrape_configs:
  - job_name: 'care-documentation-service'
    scrape_interval: 30s
    static_configs:
      - targets: ['producer1.example.com:9090']
    metrics_path: '/metrics'

Audit Logging (PDL Compliance)

Required Audit Information

Every access must log:

• Who: User identity (personnummer or HSA-ID)
• What: Patient identity accessed
• When: Timestamp
• Where: System/organization
• Why: Purpose (PDL purpose code)
• Result: Success or failure

Audit Log Format

Structured Log Example:

{
  "timestamp": "2024-10-27T14:32:15.123Z",
  "requestId": "REQ-2024-123456",
  "service": "GetCareDocumentation",
  "user": {
    "id": "197001011111",
    "name": "Dr. Anna Andersson",
    "hsaId": "SE2321000016-1234-DOC001",
    "organization": "Karolinska"
  },
  "patient": {
    "id": "197001011234",
    "idType": "1.2.752.129.2.1.3.1"
  },
  "purpose": "CARE",
  "result": "OK",
  "dataReturned": {
    "recordCount": 15,
    "systems": ["SE2321000016-SYS1", "SE2321000016-SYS2"]
  },
  "blocked": false,
  "consentChecked": true
}

Audit Log Retention

• Minimum: 10 years (Swedish requirements)
• Format: Immutable, tamper-evident
• Access: Restricted, logged

Operations Procedures

Deployment Procedure

1. Pre-Deployment
   • Backup current configuration
   • Review release notes
   • Verify test environment success
   • Schedule maintenance window
   • Notify stakeholders
2. Deployment
   • Stop service (or deploy to standby)
   • Deploy new version
   • Update configuration
   • Run smoke tests
   • Switch traffic to new version
3. Post-Deployment
   • Monitor error rates
   • Verify logs
   • Run integration tests
   • Update documentation
   • Close maintenance window
4. Rollback Plan
   • Criteria for rollback defined
   • Rollback procedure documented
   • Previous version available

Incident Response

Severity Levels:

P1 - Critical:

• Service completely unavailable
• Data breach
• Response: Immediate, 24/7

P2 - High:

• Degraded service (> 10% errors)
• Performance severely impacted
• Response: Within 1 hour

P3 - Medium:

• Intermittent issues
• Single system affected
• Response: Within 4 hours

P4 - Low:

• Minor issues
• No user impact
• Response: Next business day

Incident Response Procedure:

1. Detection - Monitor alerts, user reports
2. Assessment - Determine severity
3. Escalation - Notify appropriate team
4. Investigation - Identify root cause
5. Resolution - Fix issue
6. Communication - Update stakeholders
7. Post-Mortem - Document and improve

Maintenance Windows

Scheduled Maintenance:

• Frequency: Monthly
• Window: Sunday 02:00-06:00 CET
• Notification: 7 days advance
• Duration: Maximum 4 hours

Emergency Maintenance:

• Criteria: P1 incident resolution
• Approval: Operations manager
• Notification: Immediate
• Duration: As needed

Capacity Planning

Resource Sizing

Consumer (per instance):

• CPU: 2 cores
• Memory: 4 GB
• Disk: 50 GB (logs)
• Network: 10 Mbps

Producer (per instance):

• CPU: 4 cores
• Memory: 8 GB
• Disk: 200 GB (database)
• Network: 100 Mbps

Scaling Triggers

Horizontal Scaling:

• CPU utilization > 70% for 5 minutes
• Add instance
• Update load balancer

Vertical Scaling:

• Memory utilization > 80%
• Response time degradation
• Plan upgrade window

Security Operations

Access Control

Service Access Matrix:

Security Monitoring

Monitor for:

• Failed authentication attempts
• Authorization failures
• Unusual access patterns
• Certificate errors
• Blocked access attempts

Alert Thresholds:

• Failed auth > 10/min: Warning
• Failed auth > 50/min: Critical (potential attack)
• ACCESS_DENIED spike: Investigate

Troubleshooting

Common Issues

Issue: Service Unavailable
Symptoms: HTTP 503, Connection Refused
Resolution:

1. Check service status
2. Verify network connectivity
3. Check certificate validity
4. Review error logs
5. Restart service if needed

Issue: Slow Response
Symptoms: Timeout, delays
Resolution:

1. Check database performance
2. Review query execution plans
3. Check EI update backlog
4. Verify network latency
5. Scale if needed

Issue: Authentication Failure
Symptoms: Certificate error, access denied
Resolution:

1. Verify certificate validity
2. Check certificate chain
3. Verify trust relationships
4. Check time synchronization (important for SAML)

References

• Testing - Test scenarios
• Security - Security requirements
• Errors - Error handling
• Architecture - System architecture