Swedish Healthcare Service - Health Condition Description
0.1.0 - CI Build Sweden

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

GetCareDocumentation

GetCareDocumentation

Version: 3.0
Contract: urn:riv:clinicalprocess:healthcond:description:GetCareDocumentation:3

Description

GetCareDocumentation returns journal entries (journalanteckningar) for a patient. These notes are of types:

  • Investigation (utredning)
  • Treatment/intervention (åtgärd/behandling)
  • Summary (sammanfattning)
  • Coordination (samordning)
  • Admission (inskrivning)
  • Discharge note including epicrisis (slutanteckning)
  • Note without physical encounter (anteckning utan fysiskt möte)
  • Inpatient note (slutenvårdsanteckning)
  • Visit note (besöksanteckning)

The message format is based on NPÖ RIV 2.2.0 and is compatible with HL7 v. 3 CDA v. 2.

Interaction Flow

Via Aggregating Service

┌─────────┐          ┌─────────────┐          ┌──────────┐          ┌────────┐  ┌────────┐
│Consumer │          │ Aggregator  │          │    EI    │          │Source1 │  │Source2 │
└────┬────┘          └──────┬──────┘          └────┬─────┘          └───┬────┘  └───┬────┘
     │                      │                      │                    │           │
     │ GetCareDoc(patient)  │                      │                    │           │
     ├─────────────────────>│                      │                    │           │
     │                      │                      │                    │           │
     │                      │ Query(patient,       │                    │           │
     │                      │  CareDocumentation)  │                    │           │
     │                      ├─────────────────────>│                    │           │
     │                      │                      │                    │           │
     │                      │  Systems: S1, S2     │                    │           │
     │                      │<─────────────────────┤                    │           │
     │                      │                      │                    │           │
     │                      │  GetCareDoc(patient) │                    │           │
     │                      ├──────────────────────┼───────────────────>│           │
     │                      │                      │                    │           │
     │                      │  GetCareDoc(patient) │                    │           │
     │                      ├──────────────────────┼────────────────────┼──────────>│
     │                      │                      │                    │           │
     │                      │                      │        Response    │           │
     │                      │<─────────────────────┼────────────────────┤           │
     │                      │                      │                    │           │
     │                      │                      │                Response        │
     │                      │<─────────────────────┼────────────────────┼───────────┤
     │                      │                      │                    │           │
     │  Response(aggregated)│                      │                    │           │
     │<─────────────────────┤                      │                    │           │
     │                      │                      │                    │           │

Direct System Access

┌─────────┐          ┌────────────┐
│Consumer │          │Source Sys  │
└────┬────┘          └─────┬──────┘
     │                     │
     │ GetCareDoc(patient, │
     │  sourceSystemHSAId) │
     ├────────────────────>│
     │                     │
     │        Response     │
     │<────────────────────┤
     │                     │

Request Structure

See the GetCareDocumentationRequest logical model for complete structure.

Key Request Parameters

Parameter Cardinality Type Description
careUnit 0..* IIType Filter on care unit (accountableCareUnit in response)
healthcareProvider 0..* IIType Filter on healthcare provider
patientId 1..1 IIType Patient identifier (12 chars, no separator)
datePeriod 0..1 DatePeriodType Limits search to date interval
sourceSystemId 0..1 IIType Limits search to specific source system
hasMoreReference 0..1 string Reference for partial data retrieval continuation

Patient ID Rules

The service producer must return all patient information for any of the patient's identity designations. This includes:

  • Personal number (personnummer) - OID: 1.2.752.129.2.1.3.1
  • Coordination number (samordningsnummer) - OID: 1.2.752.129.2.1.3.3
  • Local reserve number - Local OID (e.g., SLL: 1.2.752.97.3.1.3)

Note: Local reserve numbers cannot be used with engagement index and aggregating services. Service consumers using reserve numbers must use direct system addressing.

Response Structure

See the GetCareDocumentationResponse logical model for complete structure.

Care Documentation Structure

Each care documentation entry contains:

Header (JoL-header v2.2)

  • Access Control Header - Information for access control decisions
    • accountableHealthcareProvider (vårdgivare)
    • accountableCareUnit (vårdenhet)
    • patientId
    • careProcessId
    • blockComparisonTime (for blocking control)
    • approvedForPatient flag
  • Source System - Identifier of source system
  • Record - Metadata about the entry
    • Unique identifier (UUID)
    • Timestamp
  • Author - Healthcare professional responsible
    • HSA-ID, name, timestamp
    • Role (befattning)
    • Organization unit
  • Signature - Digital signature information (if signed)

Body

  • Clinical Document Note Code (required) - Type from KV Anteckningstyp (1.2.752.129.2.2.2.11)
  • Title (optional)
  • Text Content (optional) - Plain text or DocBook v5.0 formatted
  • Multimedia Entry (optional) - Embedded binary or external reference
  • Dissenting Opinion (0..*) - Patient or guardian's dissenting opinions

DocBook Format Support

Text content may be formatted using DocBook version 5.0 standard. Required elements that must be supported by consumers:

  • version
  • article
  • title
  • info
  • para
  • section
  • bibliography

Text must be entity-encoded when transmitted (e.g., > becomes &gt;, < becomes &lt;).

Message Examples

Example Request (SOAP)

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:riv="urn:riv:clinicalprocess:healthcond:description:GetCareDocumentationResponder:3"
               xmlns:add="http://www.w3.org/2005/08/addressing">
  <soap:Header>
    <add:To>https://service-platform.example.se/GetCareDocumentation</add:To>
    <add:Action>urn:riv:clinicalprocess:healthcond:description:GetCareDocumentationResponder:3:GetCareDocumentation</add:Action>
    <add:MessageID>uuid:12345678-1234-1234-1234-123456789abc</add:MessageID>
    <riv:LogicalAddress>5565594230</riv:LogicalAddress>
  </soap:Header>
  <soap:Body>
    <riv:GetCareDocumentation>
      <riv:patientId>
        <riv:id>197001011234</riv:id>
        <riv:type>1.2.752.129.2.1.3.1</riv:type>
      </riv:patientId>
      <riv:timePeriod>
        <riv:start>20240101</riv:start>
        <riv:end>20241231</riv:end>
      </riv:timePeriod>
      <riv:careUnitHSAId>SE2321000016-1234</riv:careUnitHSAId>
    </riv:GetCareDocumentation>
  </soap:Body>
</soap:Envelope>

Example Response (Simplified)

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:riv="urn:riv:clinicalprocess:healthcond:description:GetCareDocumentationResponder:3">
  <soap:Body>
    <riv:GetCareDocumentationResponse>
      <riv:result>
        <riv:resultCode>OK</riv:resultCode>
      </riv:result>
      <riv:careDocumentation>
        <riv:careDocumentationHeader>
          <riv:documentId>DOC-2024-001</riv:documentId>
          <riv:sourceSystemHSAId>SE2321000016-SYS1</riv:sourceSystemHSAId>
          <riv:documentTime>20240315143000</riv:documentTime>
          <riv:patientId>
            <riv:id>197001011234</riv:id>
            <riv:type>1.2.752.129.2.1.3.1</riv:type>
          </riv:patientId>
          <riv:accountableCareUnit>
            <riv:healthcareFacility>SE2321000016-1234</riv:healthcareFacility>
          </riv:accountableCareUnit>
          <riv:approvedForPatient>true</riv:approvedForPatient>
          <riv:nullified>false</riv:nullified>
        </riv:careDocumentationHeader>
        <riv:careDocumentationBody>
          <riv:clinicalDocumentNote>
            <riv:clinicalDocumentNoteText>Patient reports improvement in symptoms...</riv:clinicalDocumentNoteText>
            <riv:noteTitle>Progress Note</riv:noteTitle>
            <riv:noteTime>20240315143000</riv:noteTime>
          </riv:clinicalDocumentNote>
        </riv:careDocumentationBody>
      </riv:careDocumentation>
    </riv:GetCareDocumentationResponse>
  </soap:Body>
</soap:Envelope>

Partial Data Retrieval

GetCareDocumentation supports partial delivery when:

  • Number of records risks exceeding 27-second response time
  • Message size exceeds limits

Usage Pattern

  1. Producer returns latest records plus hasMore element with:
    • logicalAddress (producer's address)
    • reference (unique identifier, valid min 1 hour)
  2. Consumer uses hasMoreReference in next request
  3. Request must be directly addressed to producer
  4. Same search parameters must be used
  5. Consumer handles duplicate detection if updates occur

Producer Requirements

  • Return most recent information not previously delivered
  • May include updated information in subsequent calls
  • Return as many records as possible within time/size limits

Business Rules

Rule: Access Control Requirements

Elements accountableHealthcareProvider and accountableCareUnit required for blocking control and PDL logging. Records without HSA-IDs for care unit won't display in coherent medical records access.

Rule: Unique Record ID

Identifier must be unique. Same ID cannot occur multiple times in response.

Rule: Content Format

Only one of clinicalDocumentNoteText or multimediaEntry may be specified.

Rule: Multimedia Entry

Only one of value (embedded) or reference (external URL) may be specified.

Rule: Binary Attachments

Producers must follow general guidelines for binary attachments (reference ARK_0038).

Rule: Source System Addressing

When sourceSystemId is specified, it must match logicalAddress in SOAP header.

DocBook Format Details

Entity Encoding Example

Original DocBook Entity Encoded
<article> &lt;article&gt;
<title>Title</title> &lt;title&gt;Title&lt;/title&gt;
<para>Text</para> &lt;para&gt;Text&lt;/para&gt;

Transformation

Consumers must:

  1. Decode entity-encoded text to restore XML syntax
  2. Transform to presentation format (XHTML, PDF) using XSLT scripts

Reference libraries available:

  • Apache Commons Text StringEscapeUtils (escapeXml/unescapeXml methods)
  • DocBook XSLT transformation scripts from docbook.org

Error Handling

Logical Errors

Error Code