Reporting API for extracting statistics, management & usage reports as well as complete reports about individuals.

Reporting REST Endpoints

Each type of report has three endpoints:

$fetch-<reportname>
- run report - run report synchronously and return resource with result.
$execute-<reportname>
- run report - run report asynchronously. The returned result is an empty placeholder that identifies the resource to be retrieved later. When finished, the resource will be updated with the result. The report will be stored in the database and will be available for retrieval.
$schedule-<reportname>
- schedule report - schedule a report for later batch execution. The returned result is an empty placeholder that identifies the resource to be retrieved later. When the batch is run, the resource will be updated with the result. The report will be stored in the database and will be available for retrieval. The scheduled reports will be generated during the night, and will usually be available the next morning.

An additional endpoint is provided for retrieving the status of asynchronously executing reports (execute, or schedule):

$get-report-job-status

Currently the following operations are supported:

Fetch Operation	Execute Operation	Schedule Operation
fetch-careplan-and-episode-of-care-stats	execute-careplan-and-episode-of-care-stats	schedule-careplan-and-episode-of-care-stats
fetch-careplan-customization-stats	execute-careplan-customization-stats	schedule-careplan-customization-stats
fetch-careplan-duration-stats	execute-careplan-duration-stats	schedule-careplan-duration-stats
fetch-careplans-by-patient	execute-careplans-by-patient	schedule-careplans-by-patient
fetch-careteam-stats	execute-careteam-stats	schedule-careteam-stats
fetch-measurement-stats	execute-measurement-stats	schedule-measurement-stats
fetch-patient-devices	execute-patient-devices	schedule-patient-devices
fetch-patient-gdpr	execute-patient-gdpr	schedule-patient-gdpr
fetch-patient-total	execute-patient-total	schedule-patient-total
fetch-practitioner-gdpr	execute-practitioner-gdpr	schedule-practitioner-gdpr
fetch-practitioner-stats	execute-practitioner-stats	schedule-practitioner-stats
fetch-ssl-orders	execute-ssl-orders	schedule-ssl-orders
fetch-patient-usage-stats	execute-patient-usage-stats	schedule-patient-usage-stats
fetch-questionnaireresponses	execute-questionnaireresponses	schedule-questionnaireresponses
Job Status Operation
get-report-job-status

Operation Input - Report Parameters

All reports require a parameter anonymization that defines the anonymization level of the data returned. Currently only two modes are available:

NONE - the data is returned without modification
ANONYMIZED - the data is anonymized by removing identifying information from patient resources, and encrypting all resource ids.

Each report endpoint may accept a number of other parameters for conditionally restricting the data included in the report. For example:

organization
period
patient
practitioner
condition
devicetype
status
seller

The report (fetch|execute|schedule)-questionnaireresponses takes a parameter _partition. It controls bin size of query partitions and is made available for internal use during testing to be able to determine the optimal configuration. When the optimal partition size has been determined, the value of partition size will be determined by deployment configuration.

The availability and semantics of each parameter is defined on individual report level. See the operations listed above for details.

Operation Output - Report Structure and Format

Report data is returned as a FHIR Binary resource with the following elements:

contentType
- the mime type of the content (application/gzip-json)
securityContext
- a reference identifying the user that requested the report. This restricts the retrieval of the report to the user.
content
- the report data in base64 zip compressed JSON format (application/gzip-json)

A report content contains a report header file and zero or more report group files, and the files are put in a zip archive in a directory structure:

directory: <name><timestamp>
- file: ReportHeader
- directory: <groupname>
  - files: <group1>
  - file: <group2>
  - ...
  - file: <groupN>

The report header file, ReportHeader, contains a JSON object with elements:

reportName
reportTime
parameters

Eg. a report header returned by $fetch-careplan-customization-stats:

{
  "reportName" : "CarePlanCustomizationStatsReport",
  "reportTime" : "2019-12-04T12:15:17.166804Z",
  "parameters" : {
    "resourceType" : "Parameters",
    "parameter" : [ {
      "name" : "anonymization",
      "valueString" : "None"
    }, {
      "name" : "organization",
      "valueReference" : {
        "reference" : "http://organization.local.ehealth.sundhed.dk/fhir/Organization/52078"
      }
    } ]
  }
}

Each report group file is named by the id of the grouping data element. The type of grouping data element depends on the report type. It may be a FHIR resource, a FHIR bundle, an SSL resource, or a report summary type.

Each group file includes the grouping resource, and one or more related resources depending on the type of report.

Eg. a report group returned by $fetch-careplan-customization-stats containing plan definition (group resource) and careplan customization summary:

{
  "EHealthPlanDefinition" : {
    "resourceType" : "PlanDefinition",
    "id" : "99949",
    "meta" : {
      "versionId" : "1",
      "profile" : [ "http://ehealth.sundhed.dk/fhir/StructureDefinition/ehealth-plandefinition" ]
    },
    "extension" : [ {
      "url" : "http://ehealth.sundhed.dk/fhir/StructureDefinition/ehealth-modifier-role",
      "extension" : [ {
        "url" : "reference",
        "valueReference" : {
          "reference" : "http://organization.local.ehealth.sundhed.dk/fhir/Organization/37133"
        }
      }, {
        "url" : "role",
        "valueCodeableConcept" : {
          "coding" : [ {
            "system" : "http://ehealth.sundhed.dk/cs/modifier-role",
            "code" : "owner"
          } ]
        }
      } ]
    } ],
    "version" : "fc72966e-68cf-4a4c-a128-1d77e03d6d1f",
    "status" : "active"
  },
  "CarePlanCustomizationSummary" : {
    "timingCustomizationCount" : 1,
    "referenceRangeCustomizationCount" : 1
  }
}

Security

Access to the reporting endpoints is restricted by security privileges:

$fetch-<reportname>- when granted, a user is authorized to perform the fetch, execute and schedule version of the report.
report-non-anonymized - when granted, a user is authorized to fetch or schedule reports with no anonymization.

The reporting service can be configured to disallow the fetch operation for selected report endpoints. This would be relevant if the operation is expected to exceed the normal request timeout (10 sec).

For system users, reports may include data from all managing organizations. The organization parameter is optional in this case.

For practitioner users, only data from the practitioner's organization will be included. The organization parameter is mandatory in this case.

Reports stored in the database can only be retrieved if the user is identical to the user that scheduled or executed the report.

Reporting Service Configuration

The configuration of the reporting service determines:

The availability of synchronous execution (fetch) for each type of report.
The schedule for batch execution and retention purge.
The retention period that a batch report will remain in the database before being purged.