Reporting API Service
Overview
The JH Reporting API Service can be run as a container or hosted dotnet core process. All configurable settings are applied through environment variables. None of the settings below are required. If left to default values, the reporting service will deploy with only the basic API enabled which allows for report and form generation.
Container Image
The container image for the Reporting API Service is hosted in Artifactory at the following path: docker/jh-reporting/reporting-api-service/
Nuget Package
If desired, the API service can be hosted in your own application. The current version of the required Nuget package can be found in Artifactory at the path: nuget/jhreporting/JackHenry.Reports.1.0.8.nupkg
UI Features
The following settings are used to enable/disable UI features of the reporting API service. None of these are required to utilize the Reporting API. The Jobs UI requires proper configuration of the Report Job API.
| Setting | Env Value | Default | Description |
|---|---|---|---|
| Reports UI | Reporting__Features__Reports | False |
Enables the Reports UI |
| Report Template Path | Reporting__ReportTemplatesPath | None | If the Reports UI is enabled, templates will be loaded from the path defined here. |
| Report Data Path | Reporting__ReportDataPath | None | If the Reports UI is enabled, report data will be loaded from the path defined here. |
| Report Resources Path | Reporting__ReportResourcesPath | None | If the Reports UI is enabled, report resources will be loaded from the path defined here. |
| Forms UI | Reporting__Features__Forms | False |
Enables the Forms UI |
| Forms Path | Reporting__ReportFormsPath | None | If the Forms UI is enabled, PDF forms will be loaded from the path defined here. |
| Dynamic | Reporting__Features__Dynamic | False |
Enables the Dynamic Reports UI |
| Jobs UI | Reporting__Features__Jobs | False |
Enables the Report Job APIs and UI. Requires proper Job API configuration as defined below. |
Azure AD Authentication
The settings below are used to configure authentication for the UI application (not the API). If authentication is not needed/desired, set AzureADAuth__Enabled to False.
| Setting | Env Value | Default | Description |
|---|---|---|---|
| Enabled | Reporting__AzureADAuth__Enabled | False |
Enables Azure AD Authentication |
| Instance | Reporting__AzureADAuth__Instance | https://login.microsoftonline.com/ |
The AzureAD Instance URL |
| ClientId | Reporting__AzureADAuth__ClientId | None | The application's Client Id |
| TenantId | Reporting__AzureADAuth__TenantId | None | The Tenant Id |
| CallbackPath | Reporting__AzureADAuth__CallbackPath | /signin-oidc |
Callback path |
Using Git repos for report templates
The following settings are used to enable the reporting engine to load report templates from a Git repo. Templates URLs should be formatted as git://[RepoName]@[path/to/template.rpt.json]. Multiple repos may be configured using an array syntax for env var names (Reporting__GitConfig__Repos__0__Name).
| Setting | Env Value | Description |
|---|---|---|
| RepoName | Reporting__GitConfig__Repos__[idx]__Name | The name of the repo. This must match the url of the template. |
| Url | Reporting__GitConfig__Repos__[idx]__Url | The Url to the git repo. |
| Branch | Reporting__GitConfig__Repos__[idx]__Branch | The Git branch to use. |
| Username | Reporting__GitConfig__Repos__[idx]__Username | The username for authenticating to the git repo. |
| PasswordSecret | Reporting__GitConfig__Repos__[idx]__PasswordSecret | The password to use for authenticating to the git repo. |
An example git config:
- Reporting__GitConfig__Repos__0__Name: "repo1"
- Reporting__GitConfig__Repos__0__Url: "github.com/JHAEA/report-templates.git"
- Reporting__GitConfig__Repos__0__Branch: "main"
- Reporting__GitConfig__Repos__0__Username: "gituser"
- Reporting__GitConfig__Repos__0__PasswordSecret: "GIT_PASSWORD"
Report Job API
The Report Job API allows for report generation at scale. Report Jobs are submitted and a ticket is returned. Report generation progress can be monitored by querying job status. When using the Job API, a Reporting Worker Service must be deployed to your environment.
| Setting | Env Value | Default | Description |
|---|---|---|---|
| Jobs | Reporting__Features__Jobs | False |
Enables the Report Job APIs and UI |
The following configurations are required when enabling the Report Job APIs:
Report Output
Reports generated through the Job API can be saved to a local file path or a GCS bucket. The following settings control this behavior:
| Setting | Env Value | Default | Description |
|---|---|---|---|
| FileConfig.OutputDir | Reporting__FileConfig__OutputDir | None | Sets the local file path for saving reports generated through the Job API. |
| GCSConfig.Enabled | Reporting__GCSConfig__Enabled | False |
Enables saving report output to a GCS Bucket. If true, file output is disabled. |
| GCSConfig.OutputBucket | Reporting__GCSConfig__OutputBucket | None | The full path to the GCS bucket where generated reports should be saved. |
Redis Config
| Setting | Env Value | Default | Description |
|---|---|---|---|
| ProjectId | Reporting__RedisConfig__ProjectId | None | The GCP Project ID of the Redis instance |
| Endpoint | Reporting__RedisConfig__Endpoint | None | The endpoint for the redis cache. Typically, an IP address. |
| Password | Reporting__RedisConfig__Password | None | The password used to connect to the Redis endpoint. |
| SslHost | Reporting__RedisConfig__SslHost | None | Used to enforce SSL host identity on the server’s certificate. |
| SslCert | Reporting__RedisConfig__SslCert | None | The SSL certificate to validate. |
| Port | Reporting__RedisConfig__Port | 6379 |
The redis endpoint port |
| InstanceName | Reporting__RedisConfig__InstanceName | None | The redis instance name |
| JobExpiration | Reporting__RedisConfig__JobExpiration | 30 |
Amount of time, in Days, that jobs should remain in the cache. |
| ResourceExpiration | Reporting__RedisConfig__ResourceExpiration | 120 |
Amount of time, in Minutes, that report resources should remain in the cache. If resources are removed before a job completes, report rendering will fail. Ensure that this duration is longer than any potential long-running job. |
PubSub Config
| Setting | Env Value | Default | Description |
|---|---|---|---|
| ProjectId | Reporting__PubSubConfig__ProjectId | None | The GCP Project ID of the PubSub queues |
| ReportTaskQueueTopic | Reporting__PubSubConfig__ReportTaskQueueTopic | None | A PubSub topic for the report task queue |
| ReportTaskQueueSubscription | Reporting__PubSubConfig__ReportTaskQueueSubscription | None | A PubSub subscription for the report task queue |
| ReportTaskCompleteTopic | Reporting__PubSubConfig__ReportTaskCompleteTopic | None | A PubSub topic for report task completion |
| ReportTaskCompleteSubscription | Reporting__PubSubConfig__ReportTaskcompleteSubscription | None | A PubSub subscription for report task completion |
Reporting Worker Service
Overview
The Reporting API Service is responsible for accepting and scheduling report Job requests. A Job is typically comprised of many individual report generations tasks. Each of these tasks is added to a PubSub Report Task queue. The Report Worker Service listens for messages on the Report Task queue, renders the report and then publishes a message to another queue indicating that the task has been completed. The Reporting API Service monitors the completed task messages and keeps track of the overall job progress. To handle large jobs with many individual report generation tasks, the Reporting Worker Service can be configured to autoscale based on the number of messages in the report task PubSub queue.
Configuration
The Reporting Worker service should be configured with the same Report Output, Redis Config and PubSub Config values as the Reporting API Service.
Container Image
The container image for the Worker Service can be found in Artifactory at the following path: docker/jh-reporting/reporting-worker-service/