Report Service

Overview

The Report service is responsible for persisting the Measure Reports and FHIR resources that the Measure Eval service generates after evaluating a patient against a measure. When a tenant's reporting period end date has been met, the Report Service performs various workflows to determine if all of the patient MeasureReports are accounted for that period prior to initiating the submission process.

flowchart LR
nReportService_1ECFD801["Service: Report Service"]
  nReportService_1ECFD801 -->|produces| nAuditableEventOccurred_2E7ED8D7["Event: AuditableEventOccurred"]
  nReportService_1ECFD801 -->|produces| nReadyForValidation_293CC34C["Event: ReadyForValidation"]
  nReportService_1ECFD801 -->|produces| nSubmitPayload_2F556666["Event: SubmitPayload"]
  nValidationComplete_7F3C0D47["Event: ValidationComplete"] -->|consumed by| nReportService_1ECFD801
  nMeasureReportGenerated_38AFFB54["Event: MeasureReportGenerated"] -->|consumed by| nReportService_1ECFD801
  nPatientEvent_34D33665["Event: PatientEvent"] -->|consumed by| nReportService_1ECFD801
  nReportScheduled_BC6D32E["Event: ReportScheduled"] -->|consumed by| nReportService_1ECFD801
  nPayloadSubmitted_2E346CAB["Event: PayloadSubmitted"] -->|consumed by| nReportService_1ECFD801
  nReportService_1ECFD801 -->|sends| nDataAcquisitionRequested_4BBEB8F8["Command: DataAcquisitionRequested"]
  nReportService_1ECFD801 -->|sends| nEvaluationRequested_7F27B0ED["Command: EvaluationRequested"]
  nGenerateReportRequested_7BC99734["Command: GenerateReportRequested"] -->|handled by| nReportService_1ECFD801
  nReportService_1ECFD801 -->|provides| nGetFacilityConfig_32C58A79["Query: GetFacilityConfig"]
  nReportService_1ECFD801 -->|provides| nGetServiceInfo_13F02E06["Query: GetServiceInfo"]
  subgraph nCompliance_DBAE25D_domain["Domain: Compliance"]
    nAuditableEventOccurred_2E7ED8D7
    nEvaluationRequested_7F27B0ED
    nMeasureReportGenerated_38AFFB54
    nReadyForValidation_293CC34C
    nValidationComplete_7F3C0D47
  end
  subgraph nDataAccess_2A523756_domain["Domain: Data Access"]
    nDataAcquisitionRequested_4BBEB8F8
  end
  subgraph nReport_4D4FBBDA_domain["Domain: Report"]
    nGenerateReportRequested_7BC99734
    nPatientEvent_34D33665
    nPayloadSubmitted_2E346CAB
    nReportScheduled_BC6D32E
    nReportService_1ECFD801
    nSubmitPayload_2F556666
  end
  subgraph nTenant_379CD514_domain["Domain: Tenant"]
    nGetFacilityConfig_32C58A79
    nGetServiceInfo_13F02E06
  end

Configuration

The following environment variables and settings are used for the Report Service:

Variable Description
ASPNETCORE_ENVIRONMENT The .NET environment (e.g., Docker, Development, Production)
ServiceInformation__ServiceName The name of the service
ServiceInformation__ProductVersion The product version
EnableSwagger Enables Swagger API documentation
KafkaConnection__BootstrapServers__0 Kafka broker address
KafkaConnection__ClientId Kafka client ID
KafkaConnection__SaslProtocolEnabled Enables SASL protocol for Kafka
KafkaConnection__SaslUsername Kafka SASL username
KafkaConnection__SaslPassword Kafka SASL password
ConnectionStrings__DatabaseConnection SQL connection string
Quartz__Scheduler__InstanceName Quartz scheduler instance name
Quartz__Scheduler__InstanceId Quartz scheduler instance ID
ConnectionStrings__Redis Redis connection string
Redis__Password Redis password
Authentication__EnableAnonymousAccess Enables anonymous authentication
Authentication__Schemas__LinkBearer__Authority Authority for LinkBearer authentication
Authentication__Schemas__LinkBearer__ValidateToken Validate LinkBearer tokens
LinkTokenService__Authority Authority for LinkTokenService
LinkTokenService__LinkAdminEmail Admin email for LinkTokenService
LinkTokenService__TokenLifespan Token lifespan for LinkTokenService
LinkTokenService__SigningKey Signing key for LinkTokenService
CORS__AllowAllOrigins Allow all origins for CORS
CORS__AllowedOrigins List of allowed origins for CORS
CORS__AllowAllMethods Allow all HTTP methods for CORS
CORS__AllowedMethods List of allowed HTTP methods for CORS
CORS__AllowAllHeaders Allow all headers for CORS
CORS__AllowedHeaders List of allowed headers for CORS
CORS__AllowedExposedHeaders List of exposed headers for CORS
CORS__AllowCredentials Allow credentials for CORS
CORS__MaxAge Max age for CORS preflight requests
Telemetry__EnableTelemetry Enables telemetry
Telemetry__EnableRuntimeInstrumentation Enables runtime instrumentation for telemetry
Telemetry__EnableOtelCollector Enables OpenTelemetry collector integration
Telemetry__OtelCollectorEndpoint OpenTelemetry collector endpoint
Telemetry__EnableAzureMonitor Enables Azure Monitor integration
Logging__LogLevel__Default Default log level
Logging__LogLevel__Microsoft.AspNetCore Log level for Microsoft.AspNetCore
Logging__LogLevel__System Log level for System
Serilog__Using__0 Serilog sink (e.g., Console, Grafana.Loki)
Serilog__MinimumLevel__Default Serilog minimum log level
Serilog__MinimumLevel__Override__Microsoft Serilog override for Microsoft
Serilog__MinimumLevel__Override__System Serilog override for System
Serilog__WriteTo__0__Name Serilog sink name (e.g., GrafanaLoki)
Serilog__WriteTo__0__Args__uri Loki logging endpoint
Serilog__WriteTo__0__Args__labels__0__key Serilog label key (e.g., app)
Serilog__WriteTo__0__Args__labels__0__value Serilog label value (e.g., link-cloud)
Serilog__WriteTo__0__Args__labels__1__key Serilog label key (e.g., component)
Serilog__WriteTo__0__Args__labels__1__value Serilog label value (e.g., Report)
Serilog__WriteTo__0__Args__propertiesAsLabels__0 Serilog property as label (e.g., app)
Serilog__WriteTo__0__Args__propertiesAsLabels__1 Serilog property as label (e.g., component)
Serilog__WriteTo__1__Name Serilog sink name (e.g., Console)
ServiceRegistry__TenantService__TenantServiceUrl Tenant service URL
ServiceRegistry__TenantService__CheckIfTenantExists Whether to check if tenant exists
ServiceRegistry__TenantService__GetTenantRelativeEndpoint Relative endpoint for tenant service
ConsumerSettings__ConsumerRetryDuration Retry durations for Kafka consumers
ConsumerSettings__DisableRetryConsumer Disable retry consumer
ConsumerSettings__DisableConsumer Disable consumer
InternalBlobStorage__ConnectionString Connection string for internal blob storage
InternalBlobStorage__BlobContainerName Blob container name for internal storage
AllowReflection Allow reflection in the service
AllowedHosts Allowed hosts for the service
ports Exposed port for the service (default: 8072)

For a full list of environment variables and their usage, see the docker-compose.yml file and the appsettings.json file.

Common Configurations

Features and Functionality

Retry Scheduling in the Report Service:

Within the Report service, retries are scheduled using Quartz.NET's in-memory scheduler. The retry jobs are managed by a dedicated RetryScheduleService that uses the "InMemoryScheduler" (registered via keyed dependency injection) to schedule and execute retry operations. This approach ensures that retry jobs are lightweight, fast, and do not persist across service restarts making them ideal for transient, short-lived retry logic where durability is not required.

Impact of InMemory vs. SQL Persistence:

Using the in-memory scheduler for retries means that retry jobs are lost if the service restarts or crashes, but this is often acceptable for retry logic that can be safely re-queued or recalculated. In contrast, SQL persistence (used for report scheduling) ensures that jobs survive restarts, support clustering, and provide fault tolerance critical for business workflows that must not be lost. This dual approach allows the Report service to balance reliability and performance: persistent scheduling for essential workflows, and fast, resource-efficient in-memory scheduling for retries and transient operations.

Different types of report generation methods:

  • Scheduled Reports - Scheduling system used to automatically create reports (aka: ScheduledReport events) based on schedule routine (ie. a CRON specification)
  • Adhoc Report - Create a ScheduledReport event manually for a one-time configuration of tenant, measures and reporting period (dates). You may optionally specify the list of patients for the report; if not specified, it will ask the census service for the patients of interest during the reporting period dates.
  • Regenerate Report - Provide a previously created report ID to re-generate the report, bypassing data acquisition and normalization, and skipping straight to evaluation. This is useful in cases where the measure has changed and a report needs to be re-evaluated against the new measure version.

Database Schema

NameTypeRequired?Length
MigrationIdstringYes150
ProductVersionstringYes32
NameTypeRequired?Length
IdintegerYes
ReportEntryIdstringYes
MeasureReportIdstringNo100
StatusstringYes50
ReportTypestringYes100
MeasureReportUristringNo1024
MeasureReportFileNamestringNo500
NameTypeRequired?Length
IdintegerYes
ReportPopulationIdstringYes
PopulationIdstringNo100
PopulationCodeJsonstringNo
TotalPopulationCountintegerYes
NameTypeRequired?Length
IdintegerYes
GroupPopulationIdintegerYes
MeasureReportIdstringYes100
PopulationCountintegerYes
NameTypeRequired?Length
IdstringYes
CreateDatestring (date-time)Yes
ModifyDatestring (date-time)No
FacilityIdstringYes100
ReportScheduleIdstringYes
PatientIdstringYes100
ReportingStatusstringYes50
SubmissionStatusstringNo50
SubmitReportDateTimestring (date-time)No
AggregateReportUristringNo1024
AggregateReportBlobNamestringNo500
NameTypeRequired?Length
IdstringYes
CreateDatestring (date-time)Yes
ModifyDatestring (date-time)No
FacilityIdstringYes100
ReportScheduleIdstringYes
MeasurestringNo200
ReportTypestringYes100
NameTypeRequired?Length
IdstringYes
CreateDatestring (date-time)Yes
ModifyDatestring (date-time)No
FacilityIdstringYes100
ReportScheduleIdstringYes
PatientIdstringYes100
MeasureReportIdstringYes100
ResourceTypestringYes100
ResourceIdstringYes100
NameTypeRequired?Length
IdstringYes
CreateDatestring (date-time)Yes
ModifyDatestring (date-time)No
FacilityIdstringYes100
ReportStartDatestring (date-time)Yes
ReportEndDatestring (date-time)Yes
SubmitReportDateTimestring (date-time)No
EnableSubmissionbooleanYes
EndOfReportPeriodJobHasRunbooleanYes
AdHocTypestringNo50
FrequencystringYes50
PayloadRootUristringNo1024
StatusstringYes50
IsDeletedbooleanNo
NameTypeRequired?Length
MeasureReportIdintegerYes
ResourceTypestringYes100
ResourceCountintegerYes
NameTypeRequired?Length
ReportScheduleIdstringYes
ReportTypestringYes100
NameTypeRequired?Length
SCHED_NAMEstringYes120
TRIGGER_NAMEstringYes150
TRIGGER_GROUPstringYes150
BLOB_DATAstringNo
NameTypeRequired?Length
SCHED_NAMEstringYes120
CALENDAR_NAMEstringYes200
CALENDARstringYes
NameTypeRequired?Length
SCHED_NAMEstringYes120
TRIGGER_NAMEstringYes150
TRIGGER_GROUPstringYes150
CRON_EXPRESSIONstringYes120
TIME_ZONE_IDstringNo120
NameTypeRequired?Length
SCHED_NAMEstringYes120
ENTRY_IDstringYes140
TRIGGER_NAMEstringYes150
TRIGGER_GROUPstringYes150
INSTANCE_NAMEstringYes150
FIRED_TIMEintegerYes
SCHED_TIMEintegerYes
PRIORITYintegerYes
STATEstringYes16
JOB_NAMEstringNo150
JOB_GROUPstringNo150
IS_NONCONCURRENTbooleanYes
REQUESTS_RECOVERYbooleanNo
NameTypeRequired?Length
SCHED_NAMEstringYes120
JOB_NAMEstringYes150
JOB_GROUPstringYes150
DESCRIPTIONstringNo250
JOB_CLASS_NAMEstringYes250
IS_DURABLEbooleanYes
IS_NONCONCURRENTbooleanYes
IS_UPDATE_DATAbooleanYes
REQUESTS_RECOVERYbooleanYes
JOB_DATAstringNo
NameTypeRequired?Length
SCHED_NAMEstringYes120
LOCK_NAMEstringYes40
NameTypeRequired?Length
SCHED_NAMEstringYes120
TRIGGER_GROUPstringYes150
NameTypeRequired?Length
SCHED_NAMEstringYes120
INSTANCE_NAMEstringYes200
LAST_CHECKIN_TIMEintegerYes
CHECKIN_INTERVALintegerYes
NameTypeRequired?Length
SCHED_NAMEstringYes120
TRIGGER_NAMEstringYes150
TRIGGER_GROUPstringYes150
REPEAT_COUNTintegerYes
REPEAT_INTERVALintegerYes
TIMES_TRIGGEREDintegerYes
NameTypeRequired?Length
SCHED_NAMEstringYes120
TRIGGER_NAMEstringYes150
TRIGGER_GROUPstringYes150
STR_PROP_1stringYes512
STR_PROP_2stringYes512
STR_PROP_3stringYes512
INT_PROP_1integerNo
INT_PROP_2integerNo
LONG_PROP_1integerNo
LONG_PROP_2integerNo
DEC_PROP_1numberNo
DEC_PROP_2numberNo
BOOL_PROP_1booleanNo
BOOL_PROP_2booleanNo
TIME_ZONE_IDstringNo80
NameTypeRequired?Length
SCHED_NAMEstringYes120
TRIGGER_NAMEstringYes150
TRIGGER_GROUPstringYes150
JOB_NAMEstringYes150
JOB_GROUPstringYes150
DESCRIPTIONstringNo250
NEXT_FIRE_TIMEintegerNo
PREV_FIRE_TIMEintegerNo
PRIORITYintegerNo
TRIGGER_STATEstringYes16
TRIGGER_TYPEstringYes8
START_TIMEintegerYes
END_TIMEintegerNo
CALENDAR_NAMEstringNo200
MISFIRE_INSTRintegerNo
JOB_DATAstringNo

OpenAPI Operations

Route Parameters

None

Query Parameters

None

Returns a report entry record for the given entry Id

Route Parameters
NameTypeRequired?Description
idYes
Query Parameters

None

Returns report entries for the given entry report schedule Id.

Route Parameters
NameTypeRequired?Description
reportScheduleIdYes
Query Parameters

None

Returns a report entry record for the given entry report schedule Id and patient Id.

Route Parameters
NameTypeRequired?Description
reportScheduleIdYes
patientIdYes
Query Parameters

None

Returns the count of report entries for the given report schedule Id.

Route Parameters
NameTypeRequired?Description
reportScheduleIdYes
Query Parameters

None

Returns a summary count of report types, reporting statuses, and submission statuses for the given report schedule Id.

Route Parameters
NameTypeRequired?Description
reportScheduleIdYes
Query Parameters

None

Returns report entry records for the given patient Id.

Route Parameters
NameTypeRequired?Description
patientIdYes
Query Parameters

None

Returns a report population record for the given Id

Route Parameters
NameTypeRequired?Description
idYes
Query Parameters

None

Returns report population records for the given report schedule Id. An optional 'reportType' parameter is available to specify which associated report type the returned population should be for.

Route Parameters
NameTypeRequired?Description
reportScheduleIdYes
Query Parameters
NameTypeRequired?Description
reportTypeNo

Returns the count of MeasureReportPopulations in the initial population for the given report schedule Id

Route Parameters
NameTypeRequired?Description
reportScheduleIdYes
Query Parameters

None

Returns a report resource record for the given report resource Id

Route Parameters
NameTypeRequired?Description
idYes
Query Parameters

None

Returns report resource entries for the given report schedule Id.

Route Parameters
NameTypeRequired?Description
reportScheduleIdYes
Query Parameters

None

Returns report resource records for the given report schedule Id and patient Id.

Route Parameters
NameTypeRequired?Description
reportScheduleIdYes
patientIdYes
Query Parameters

None

Returns report resource records for the given patient Id.

Route Parameters
NameTypeRequired?Description
patientIdYes
Query Parameters

None

Returns a scheduled report record for the given report schedule Id

Route Parameters
NameTypeRequired?Description
idYes
Query Parameters
NameTypeRequired?Description
includeDeletedNoWhen set to `true`, includes soft-deleted report schedules. Defaults to `false`.

Soft deletes a single report schedule by its ID.

Route Parameters
NameTypeRequired?Description
idYesThe ID of the report schedule to soft delete.
Query Parameters

None

Returns scheduled reports for the given facility Id. An optional 'active' parameter is available to only return current active reports. An optional 'blocking' parameter filters to only reports with statuses that block facility deletion (New, EndOfPeriod). An optional 'includeDeleted' parameter is available to include soft-deleted reports.

Route Parameters
NameTypeRequired?Description
facilityIdYes
Query Parameters
NameTypeRequired?Description
activeNo
blockingNoWhen set to `true`, returns only report schedules with a status of `New` or `EndOfPeriod` � the statuses that indicate a report is actively in progress and would block a facility soft-delete. Defaults to `false`.
includeDeletedNoWhen set to `true`, includes soft-deleted report schedules. Defaults to `false`.

Restores a single soft-deleted report schedule by its ID.

Route Parameters
NameTypeRequired?Description
idYesThe ID of the report schedule to restore.
Query Parameters

None

Sets the deleted status for all report schedules associated with a facility.

Route Parameters
NameTypeRequired?Description
facilityIdYesThe unique identifier of the facility.
Query Parameters
NameTypeRequired?Description
deletedNoWhen set to `true`, marks all report schedules for the facility as deleted. When set to `false`, restores all previously deleted report schedules.

Health check endpoint

Route Parameters

None

Query Parameters

None

Relationships

flowchart LR
nReportService_1ECFD801["Service: Report Service"]
  nReportService_1ECFD801 -->|produces| nAuditableEventOccurred_2E7ED8D7["Event: AuditableEventOccurred"]
  nReportService_1ECFD801 -->|produces| nReadyForValidation_293CC34C["Event: ReadyForValidation"]
  nReportService_1ECFD801 -->|produces| nSubmitPayload_2F556666["Event: SubmitPayload"]
  nValidationComplete_7F3C0D47["Event: ValidationComplete"] -->|consumed by| nReportService_1ECFD801
  nMeasureReportGenerated_38AFFB54["Event: MeasureReportGenerated"] -->|consumed by| nReportService_1ECFD801
  nPatientEvent_34D33665["Event: PatientEvent"] -->|consumed by| nReportService_1ECFD801
  nReportScheduled_BC6D32E["Event: ReportScheduled"] -->|consumed by| nReportService_1ECFD801
  nPayloadSubmitted_2E346CAB["Event: PayloadSubmitted"] -->|consumed by| nReportService_1ECFD801
  nReportService_1ECFD801 -->|sends| nDataAcquisitionRequested_4BBEB8F8["Command: DataAcquisitionRequested"]
  nReportService_1ECFD801 -->|sends| nEvaluationRequested_7F27B0ED["Command: EvaluationRequested"]
  nGenerateReportRequested_7BC99734["Command: GenerateReportRequested"] -->|handled by| nReportService_1ECFD801
  nReportService_1ECFD801 -->|provides| nGetFacilityConfig_32C58A79["Query: GetFacilityConfig"]
  nReportService_1ECFD801 -->|provides| nGetServiceInfo_13F02E06["Query: GetServiceInfo"]
  subgraph nCompliance_DBAE25D_domain["Domain: Compliance"]
    nAuditableEventOccurred_2E7ED8D7
    nEvaluationRequested_7F27B0ED
    nMeasureReportGenerated_38AFFB54
    nReadyForValidation_293CC34C
    nValidationComplete_7F3C0D47
  end
  subgraph nDataAccess_2A523756_domain["Domain: Data Access"]
    nDataAcquisitionRequested_4BBEB8F8
  end
  subgraph nReport_4D4FBBDA_domain["Domain: Report"]
    nGenerateReportRequested_7BC99734
    nPatientEvent_34D33665
    nPayloadSubmitted_2E346CAB
    nReportScheduled_BC6D32E
    nReportService_1ECFD801
    nSubmitPayload_2F556666
  end
  subgraph nTenant_379CD514_domain["Domain: Tenant"]
    nGetFacilityConfig_32C58A79
    nGetServiceInfo_13F02E06
  end