Reports
SBN clients such as SBN and SBN Anywhere fetch finished SBN reports from APIEngine by report queue number. How APIEngine gets the report file depends on the release line. In v95 and earlier, APIEngine runs Crystal Reports on its own server and reads the output from a local folder. In v96 and later, APIEngine asks the SBN Report Service for the file through the SBN Services Dashboard and passes it back to the caller.
How a report request flows
The upper lane is v95 and earlier; the lower lane is v96 and later.
Report routes
| Route | v95 and earlier | v96 and later | What it does |
|---|---|---|---|
| GET /api/v1/reports/run/{reportQueueNumber} | Yes | No | Runs the queued report on the APIEngine server with Crystal Reports and writes the output to the report destination folder. Returns true when the run finishes |
| GET /api/v1/reports/retrieve/{reportQueueNumber}/{fileType} | Yes | Yes | Returns the finished report file as a download. fileType is optional and defaults to pdf |
| GET /api/v1/reports/position/{reportQueueNumber} | No | Yes | Returns where a queued report sits in the report queue |
| GET /api/v1/diagnostic/reportservices | No | Yes | Checks each configured Report Service connection. Requires a signed-in token |
The report file is found by name: the value of the SBN option rptfname followed by an underscore (when rptfname is set), then the queue number, for example SBN_12345.pdf. When more than one file matches, the file in a format other than .pdf or .rpt is returned; otherwise the .pdf is returned. The .rpt file is never returned.
v95 and earlier: Crystal Reports on the APIEngine server
APIEngine renders reports itself with the SAP Crystal Reports runtime, so the runtime must be installed on the APIEngine server. The required version is listed on Crystal Reports Runtimes; for v95 it is the 64-bit runtime for .NET Framework, 13.0.40.5789. APIEngine locates the installed runtime the first time a report runs.
The folders are set in the Reporting section of the Settings page. Each has a Test button that checks the folder and, when access is missing, shows the icacls command to run.
| Setting | Holds |
|---|---|
| Crystal Report Source (.rpt) Path | The Crystal report templates (.rpt files). APIEngine needs read access |
| Crystal Report Destination (.pdf, etc.) Path | The finished report files. The retrieve route reads from here. APIEngine needs read and write access |
| Dealer Branding Images Path | Dealer logo images printed on reports |
| Data XML Path | The report data written as XML, when XML output is turned on |
A report can be produced as PDF, HTML, RTF, TXT, XLS, XLSX or XML; the format comes from the report request. A PDF is always written alongside it.
When no file matches, the retrieve route answers 204 No Content. When the destination path is blank the route returns the error "Report PDF path is not configured.", and when the folder cannot be read it returns "Unable to access report directory" with the path. The full diagnostic (GET /api/v1/diagnostic) includes a row for each report folder.
v96 and later: the SBN Report Service
APIEngine runs no report engine. Reports are generated by the Report Service, and APIEngine fetches the finished file from the SBN Services Dashboard on the server that runs it, over HTTPS with a Dashboard API key. The Crystal Reports runtime is needed on the Report Service server only.
The file comes back to the caller unchanged, as a download named report_{reportQueueNumber}.{fileType} with the content type of the file the Report Service wrote. When no file matches, the caller receives the same download with an empty body.
Create the API key
On the Dashboard of the server that runs the Report Service, open the API Keys tab and create a key (see Creating an API key). Under Features tick:
- Download Report, to retrieve finished reports
- Queue Position, for the position route
- List Files, used by the connection check
Leave the Report Service included under Services. Copy the secret when it is shown.
Configure APIEngine
The connection is the ReportServices block in App_Data\apiengine.settings. The Settings page has no fields for it, so edit the file in a text editor and then recycle the application pool.
| Field | Description |
|---|---|
| Enabled | true turns report retrieval on. When false, the report routes return "Report services retrieval is not configured (disabled, or no instance has a URL)." |
| TimeoutSeconds | How long to wait for each Dashboard call. Default 30 |
| AllowInvalidCertificates | true accepts a self-signed or otherwise untrusted Dashboard certificate for every instance |
| Instances | One entry per Report Service server. APIEngine tries them in order and uses the first that answers |
| Url | The Dashboard address of that server |
| ApiToken | The API key secret from the Dashboard |
| ReportServiceId | The Report Service id on that Dashboard. Default SBNReport |
| Down | true skips this instance without calling it |
| AllowInvalidCertificates (per instance) | true accepts an untrusted certificate for this instance only |
Saving the Settings page rewrites apiengine.settings from the fields on the page, which resets the ReportServices block. Re-apply the block after saving the Settings page.
Check the connection
At startup APIEngine checks each instance once and writes a line to its log for each one, starting "ReportServices instance". The same check runs on demand: sign in with POST /api/v1/auth/basic and call GET /api/v1/diagnostic/reportservices with the token. Each instance reports a status and a feedback message. The API key itself is never returned; tokenConfigured shows whether one is set.
| Status | Feedback | Fix |
|---|---|---|
| Ok | OK - token accepted and 'PDFPath' is available on SBNReport | None |
| Ok, with a warning | Token accepted, but 'PDFPath' is not among the browsable roots | Set the report output folder in the Report Service properties on the Dashboard |
| TokenRejected | Token rejected (401) | The key is wrong, expired, revoked or disabled, or the APIEngine server address is outside the key's allowed addresses. Create a new key |
| Forbidden | Forbidden (403): the token is valid but lacks the required capability | Tick the named feature on the key |
| ServiceNotFound | Service 'SBNReport' was not found on this host | Correct ReportServiceId, or point Url at the server that runs the Report Service |
| Unreachable | Unreachable: timed out, or a network or certificate error | Check the Url, the firewall and the Dashboard certificate |
| Skipped | Marked down by the operator - not probed | Set Down to false when the instance is back |
When every instance fails, the report routes answer HTTP 500 with "All report service instances failed:" followed by the reason for each instance. A report that is not written yet is a normal empty download; the position route shows how many reports are ahead of it.
Queue position
GET /api/v1/reports/position/{reportQueueNumber} returns queueNumber, position and statno. position counts the reports ahead of this one on the same serial; 0 means none are ahead, and statno is the queue entry's own status. An unknown queue number returns 404 with the error report_not_found. A data server without the queue-position procedure returns 501 with the error not_supported_on_data_server.
Version differences
| Area | v95 and earlier | v96 and later |
|---|---|---|
| Report generation | APIEngine, with Crystal Reports on the APIEngine server | The SBN Report Service |
| Crystal Reports runtime | Required on the APIEngine server | Required on the Report Service server only |
| Run route | /api/v1/reports/run | None |
| Position route | None | /api/v1/reports/position |
| Where the file comes from | The local Crystal Report Destination folder | The Report Service output folder, through the SBN Services Dashboard |
| Configuration | Reporting section of the Settings page | ReportServices block in apiengine.settings |
| No matching file | 204 No Content | Empty-bodied download |
| Download name | The report file's own name | report_{reportQueueNumber}.{fileType} |
| Checks | Report folder rows in the full diagnostic | /api/v1/diagnostic/reportservices and the startup log |