ISoft Wiki - User contributions [en]

Web Report Viewer Troubleshooting

2026-04-21T18:31:40Z

Ckaup: /* Common Errors (Table Mode) */

This article applies to Presage Web and ITrack Chromium. The web Report Viewer will give a general error, error details are logged to the reportqueue table and can be viewed in the "History" (web) or "Print Queue" (desktop) tab of the Report Viewer screen.

== Terms ==

* Crystal Server - the Node.JS application that uses Report Commander to generate the report PDF. Runs on Bunnahabhain. '''This application is not the same as Report Queue.'''
* Report Commander - command line application used to generate report PDFs by the Crystal Server (and Report Queue)
* Report Queue - python application that reads from reportqueue table to send emails and print to a printer. '''Report Queue is separate from Crystal Server, and the two systems do not interact.'''
* reportqueue - a table in the database that logs report runs.
* reportparameter - a table in the database that associates parameters to reports

== FAQ ==

=== How does the web report viewer work? ===

Since we can't run crystal reports directly in the browser, we need to run them on a central server and send them back to the web browser. There are multiple servers involved in this process, which I'll outline below

* The report and parameter list are loaded from the application's API (Chromium, Presage API, EE API)
* The user selects a report, fills out parameters, and clicks "Preview"
* A request is sent to the application backend (Chromium, Presage API, EE API)
* Application backend sends a request to Crystal Server, running on Bunnahabhain, or a customer server if relevant. This requests includes details of the report to run, which database to run it on, and a valid session token for that database.
* Bunnahabhain takes this request, and attempts to validate the given session token in the given database. If this fails, such as if the token is invalid or it can't connect to the database, an "Invalid Session" error is thrown.
* After the session is validated, Crystal Server will download the report file from the customer's database, and run default parameter queries. The report is saved to the "cache directory" specified in the config, with the file's hash as the file name.
* Then, Crystal Server creates a command line string to run Report Commander for the given report and parameters
* Report Commander is then invoked to generate the PDF, connecting to the database with ODBC. The PDF is saved to a folder in the Crystal Server's "cache directory". If Report Commander throws an error, it is forwarded to the application API (Chromium, Presage API, EE API), which saves it to the <code>reportqueue</code> table and forwards that error to the client, where it is displayed.
* If it succeeds, the report file is base64 encoded and sent back to the application API (Chromium, Presage API, EE API), along with the time it took to execute the report.
* The application API receives the request, saves the details to <code>reportqueue</code>/<code>reportqueueparameter</code>, and returns the base64 encoded PDF to the client
* The client receives the response from its backend, and displays the base64 encoded PDF in the browser using an <code><object/></code> tag

==== How is that different from desktop? ====

ITrack desktop talks directly to the Crystal Reports SDK on the individual workstation, instead of sending report jobs to a central server (Bunnahabhain) running Crystal Server.

=== Why can't web work the same way as desktop? ===

Chromium, Presage Web, and Enterprise Web run inside of a web browser, and can therefore be used on multiple operating systems without installing anything. Crystal Reports SDK is Windows-only and requires installation. Therefore, we need a central server to generate the pdf and send it back to the web browser (with some extra steps in between)

=== Why does this report run on desktop, but not on web? ===

As outlined above, web and desktop have entirely different stacks for running crystal reports. In short, web uses Report Commander instead of the Crystal SDK. I don't know exactly how the official Crystal SDK works, but it seems to be more tolerant to being passed extra parameters, or missing parameters. Report Commander is pickier so it will throw when you give it an extra parameter not found in the report, or if you are missing a required parameter value. As a result, basically every error in this Wiki article is web-exclusive.

=== Why aren't reports updated automatically in the web? ===

Report updates were historically done by ITrack/Presage desktop, and there is currently no system for automatically updating reports without using desktop. One is in progress, but as of 2/4/2026, it is not ready for primetime.

=== Why do I sometimes get "504 Gateway Timeout" when running a report in web? ===

As outlined above, there are multiple web servers involved in the process of generating a PDF from a Crystal Report in the web, and each one of them has their own server-level timeouts. The web server connecting you to the application API (Chromium, Presage API, EE API) might time you out, and so might the web server connecting the application API to the Crystal Server.

==== Can we make the timeouts longer? ====

The short answer is "not really". Since the timeouts are at the web server level (i.e., nginx/Apache) all requests to that server have the same timeout. We could decide not to time any request out until several minutes have passed, but if a request is taking that long, it ''should'' time out.

=== How is Report Queue, the Python application, involved in this? ===

It's not. Crystal Server and Report Queue are completely separate applications. Crystal Server only generates PDF previews. Report Queue handles printing and emailing reports. Crystal Server is written in Node.js, Report Queue is written in Python. Their main similarity is that they both invoke Report Commander to generate the PDF file, and log to the <code>reportqueue</code> table.

=== Why do Presage customers need set up manually? ===

Presage customers (generally) are on their own VM, and therefore database server. Therefore, they need their own entries in the Crystal Server config file.

Theoretically SMB customers, since they're on the same server, could share a config, but that hasn't been explored as of 2/4/2026.

=== Why do Enterprise customers need set up manually? ===

Enterprise customers are generally on their own VM or server. Additionally, EE customers might not want to use our central server, and might want to host their own. Therefore, they need their own entries in the Crystal Server config file, or their own Crystal Server instance entirely.

=== Why don't Chromium customers need to be set up manually? ===

Since Chromium users are on one of three servers, (except for dev, demo, etc.) all Chromium instances can just use the config for their regional server

== Common Errors (Table Mode) ==

This table will hold the answers to (probably) any error you will encounter running reports in Presage Web

{| class="wikitable" style=""
|+ Common Errors
|-
! style="min-width: 100px;"| Error !! Description !! How to Fix
|-
| Invalid Session. Try logging out and logging back in. || This means that the report server was not able to verify your session. Either your session has expired, or the Crystal Server is not configured for that database. The most likely cause of this is, if logging out and back in doesn't fix it, is that the (generally Presage) customer hasn't been set up on the Crystal Server, or some configuration has changed. || If the config for that customer is missing, then add it matching the template. If it is present, make sure that the Crystal Server and Chromium/Presage API are configured with the same DB URL. Otherwise, check the ODBC connection and DB credentials. Charles can check the logs to double check the URLs are good, as well as update the config file. Brian can then restart the Crystal Server service to load the updated configuration.
|-
| rowspan="5" |Error running report. Double check the report parameters and try again. || This means that Report Commander did not receive the correct amount of parameters for the report. Often times, the report will run fine on desktop, because the Crystal SDK can "fill in the gaps" or ignore extra parameters, while the web Report Viewer cannot, and needs a row in reportparameter for every parameter. Check the <code>Report Viewer > History</code> tab for more error details || Generally, update the report and re-run adders, but '''See Below''' for more details, and check <code>Report Viewer > History</code> for more parameter and error details. If updating the report and adder doesn't fix it, it's possible that they are out of date and need fixed.
|-
| '''"Invalid value for <parameter>"''' means Report Commander received an invalid value for the listed parameter. Usually this just means you forgot to fill a parameter out, but could be caused by by an outdated report / adders. || Make sure all parameters are filled out.
|-
| '''"Parameter not found in report: <parameter>"''' means that a parameter was passed to the report that the report doesn't expect. || If caused by an out-of-date report (more common), update the report. If caused by out-of-date adders, re-run adders.
|-
| '''"Missing parameter values"''' means that the report was not passed all expected parameters. Normally, this is because a parameter was added to the report, and the adders are out of date. || Re-run adders.
|-
| '''"The types of the parameter field and parameter field current values are not compatible"''' means that Crystal was passed a parameter value of the wrong type for that parameter. For example, a string instead of a number || Make sure ITrack is sending parameters of the type the report expects to receive
|-
|| (I can't remember the error message) || Missing / invalid ODBC configuration. I think this presents as "could not connect to the database" or something to that effect. Sometimes it'll give you a "database vendor code" just like ITrack desktop. || Depending on the error code, Brian can make sure the ODBC connection is valid, and give Charles the name to check that the ODBC connection name in the Crystal Server config is correct. But some error codes like 1064 are unrelated to the odbc setup
|-
|| "Invalid Report" or "No report found of type <type> and name <name>" || The Crystal Server failed to find the report with the specified name/type. || Make sure the report exists in the customer database with the given name and type, and a valid <code>report.fileid</code>. In Presage, there used to be a bug where running reports with a non-English language selected would fail with this error.
|-
|| The file or directory is corrupted and unreadable || This would come up every so often because the D drive on Bunnahabhain was failing. It shouldn't happen anymore. || It shouldn't happen again, but if it does, delete the cached report file from <code>M:\report_cache</code> on Bunnahabhain. Maybe reupload the report if it persists after that.
|-
|| Database logon failed || ODBC could not connect to the database || Ask Brian (or maybe someone else from @Systems) to double check the ODBC connection on Bunnahabhain for that customer
|-
|| <code>Database Vendor Code (code)</code> || There was some MySQL error. Look up the error code. || Might depend on the error code, but it's probably because of a bad query in the report. Reupload report. If some parameters are missing or blank, there could have been an issue running a report parameter query, and omitting those parameters could have caused a syntax error (1064)
|-
|| <code>Internal Server Error</code> || You're probably on a version of EEW that doesn't forward the error to the client properly. || Check Report Viewer > History to see the actual error
|}

=== Other Errors ===

<code>Error: WARNING: MYSQL_OPT_RECONNECT is deprecated and will be removed in a future version.</code> - Disable "Auto Reconnect" on ODBC. Presents as "Unkown Error" or "Internal Server Error" in the UI

== Logs ==

The log file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\crystalserverservice.log</code>

A normal log entry for a report job looks like this:

<pre>
Connection created for 'hosteddb-southeast.isoftdata.com.373487'
args [
'-report="D:\\Node\\crystal-reports-server\\cache\\A95AC82D42C7A2A9AFF9F720DA5F3159.rpt"',
'-login!={server:reporting_hosted_southeast}{database:373487}',
'-exportfile="D:\\Node\\crystal-reports-server\\cache\\output\\default_invoice_2024-12-03T19-20-25.872Z.pdf"',
'-exportformat="PDF"',
'-namedparameters invoicenum="5150"'
]
Destroying connection for 'hosteddb-southeast.isoftdata.com.373487'
</pre>

If you see a message like this, then the Crystal Server (not ODBC) failed to connect to the database, and there will probably be a logged request body right below it. The logged request body should have the db host sent from the application, which can be compared to the valid hosts in the config file

<pre>
Destroying connection for 'iceriver.presageanalytics.com.UNKNOWN DATABASE'
</pre>

The most common errors you'll see start like this and will show the command used to run Report Commander as well as a more-detailed error message in a mess of JSON.

<pre>
ReportError: A Report Commander error has occurred
</pre>

== Configuration ==

This will go over how to configure a customer on the Crystal Server, not so much how to deploy and configure a new Crystal Server.

The config file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\config.json</code>

Generally, you just need to set the host, user, password, and odbc data sources for a new connection. However, host MUST be unique, and MUST match the ITrack/Presage server config, as that's what's used to look up the rest of the connection info. Most of the time you can just add another entry to the JSON, like so

<code><pre>{
"host": "HOST",
"user": "USER",
"password": "PASSWORD",
"odbcDataSource": "ODBC DATA SOURCE NAME"
}</pre></code>

In some cases you might also need to set the <code>caPath</code>, <code>certPath</code>, <code>keyPath</code> properties depending on the SSL config. See other configured hosts for examples.

After adding to the JSON, restart the <code>CrystalServer</code> service to apply any changes. See below for more product-specific details.

=== Chromium ===

Does not have to be configured per-customer. One config per VM. The users have more security and so they use more of the SSL options than other users

=== Presage Web/API ===

<code>REPORT_SERVER_URI</code> specifies the report server URI used by the server, and <code>MYSQL_HOST</code> specifies the DB host. <code>EXTERNAL_DB_HOST</code> will be sent to the Crystal Server instead of <code>MYSQL_HOST</code>, if specified. '''Either <code>MYSQL_HOST</code> or <code>EXTERNAL_DB_HOST</code> MUST match the <code>host</code> in the Crystal Server config file or it will not work!'''

==== SMB ====

Currently (12/04/2024), Culligan GI is the only Presage SMB customer, and was configured individually. Maybe in the future, Presage SMB will work like Chromium and just have one config per VM, but that's not currently the case.

Since the setup for SMB clients is slightly different, the <code>MYSQL_HOST</code> is an "internal" IP, but we need an external host that matches what the Crystal Server knows. To get around this, specify this ENV variable:<code>EXTERNAL_DB_HOST: <customername>-database.presageanalytics.com</code>. Make sure the URL matches the one in the Crystal Server config. Apparently, SMB DB URLs will always have <code>-database</code> in them since the SMB docker containers don't run on the same iron as MySQL.

As of 02/03/2025, there's also Bartlett, which had some issues setting it up related to SSL. Brian fixed it, I'm not sure what he did. I think they're also set up slightly differently than Culligan GI

==== Self-Hosted ====

If they're okay hitting our Crystal Server, we just need to make sure that their database can be reached on Bunnahabhain, then the setup is the same as a hosted yard.

If not, we'll have to deploy it to a Windows server they control, and set the <code>REPORT_SERVER_URI</code> ENV variable in the API to the proper URI. Presage API will have to be able to reach <code><The Server URL>/process_report</code> in order to generate the reports

=== Enterprise Web/API ===

If we host the customer, we should just set them up on our Crystal Server. Follow the general steps for configuring them in the Crystal Server config.json, then set some ENV variables in Portainer:

* <code>REPORT_SERVER_URI: http://print.itrackchromium.com</code>
* <code>EXTERNAL_DB_HOST: example-url.itrackenterprise.com</code>

WG, UT&W, & QBT are currently (07/08/25) the only EE customers with the web report viewer on, and they also had to have the caPath set in the crystal server config to the old/not-2024 ca cert. Not sure if that'll be true for other EE customers, but it was for them.

If they're self hosted, and don't want to use our Crystal Server, follow the steps under "Deployment", then set the above ENV variables to the proper values for their setup.

== Updating ==

Not 100% sure since it's been awhile, but I'm pretty sure the process is basically:
1. Build the Crystal Server to an exe again
2. Replace the old exe on BH
3. Restart CrystalServer service

== Deployment ==

For 99% of customers, this section will not apply. But in the event that a self-hosted customer wants to host their own Crystal Server, this is probably how.

* Locate a Windows Server
* Install Report Commander on it
* Run CrystalServerSetup.exe from dl.isoftdata.com, I think this sets up the service to make it run in the background and on startup?
* Get the latest EXE or build a new one from https://github.com/ISoft-Data-Systems/crystal-reports-server and replace the old EXE from the installer
* Restart the CrystalServer service
* Make sure the service is reachable from wherever the Presage API is running
* At this point, they should be able to make a request to <code>serveruri</code>/process_report and get a report back.

== Misc / Notes ==

Housby has Crystal Server deployed to generate invoice PDFs for an ecommerce integration. They're using a version before we compiled it to an exe, so if they ever run into bugs or need an update it will be a little different

Web Report Viewer Troubleshooting

2026-03-26T18:50:28Z

Ckaup: /* Common Errors (Table Mode) */

This article applies to Presage Web and ITrack Chromium. The web Report Viewer will give a general error, error details are logged to the reportqueue table and can be viewed in the "History" (web) or "Print Queue" (desktop) tab of the Report Viewer screen.

== Terms ==

* Crystal Server - the Node.JS application that uses Report Commander to generate the report PDF. Runs on Bunnahabhain. '''This application is not the same as Report Queue.'''
* Report Commander - command line application used to generate report PDFs by the Crystal Server (and Report Queue)
* Report Queue - python application that reads from reportqueue table to send emails and print to a printer. '''Report Queue is separate from Crystal Server, and the two systems do not interact.'''
* reportqueue - a table in the database that logs report runs.
* reportparameter - a table in the database that associates parameters to reports

== FAQ ==

=== How does the web report viewer work? ===

Since we can't run crystal reports directly in the browser, we need to run them on a central server and send them back to the web browser. There are multiple servers involved in this process, which I'll outline below

* The report and parameter list are loaded from the application's API (Chromium, Presage API, EE API)
* The user selects a report, fills out parameters, and clicks "Preview"
* A request is sent to the application backend (Chromium, Presage API, EE API)
* Application backend sends a request to Crystal Server, running on Bunnahabhain, or a customer server if relevant. This requests includes details of the report to run, which database to run it on, and a valid session token for that database.
* Bunnahabhain takes this request, and attempts to validate the given session token in the given database. If this fails, such as if the token is invalid or it can't connect to the database, an "Invalid Session" error is thrown.
* After the session is validated, Crystal Server will download the report file from the customer's database, and run default parameter queries. The report is saved to the "cache directory" specified in the config, with the file's hash as the file name.
* Then, Crystal Server creates a command line string to run Report Commander for the given report and parameters
* Report Commander is then invoked to generate the PDF, connecting to the database with ODBC. The PDF is saved to a folder in the Crystal Server's "cache directory". If Report Commander throws an error, it is forwarded to the application API (Chromium, Presage API, EE API), which saves it to the <code>reportqueue</code> table and forwards that error to the client, where it is displayed.
* If it succeeds, the report file is base64 encoded and sent back to the application API (Chromium, Presage API, EE API), along with the time it took to execute the report.
* The application API receives the request, saves the details to <code>reportqueue</code>/<code>reportqueueparameter</code>, and returns the base64 encoded PDF to the client
* The client receives the response from its backend, and displays the base64 encoded PDF in the browser using an <code><object/></code> tag

==== How is that different from desktop? ====

ITrack desktop talks directly to the Crystal Reports SDK on the individual workstation, instead of sending report jobs to a central server (Bunnahabhain) running Crystal Server.

=== Why can't web work the same way as desktop? ===

Chromium, Presage Web, and Enterprise Web run inside of a web browser, and can therefore be used on multiple operating systems without installing anything. Crystal Reports SDK is Windows-only and requires installation. Therefore, we need a central server to generate the pdf and send it back to the web browser (with some extra steps in between)

=== Why does this report run on desktop, but not on web? ===

As outlined above, web and desktop have entirely different stacks for running crystal reports. In short, web uses Report Commander instead of the Crystal SDK. I don't know exactly how the official Crystal SDK works, but it seems to be more tolerant to being passed extra parameters, or missing parameters. Report Commander is pickier so it will throw when you give it an extra parameter not found in the report, or if you are missing a required parameter value. As a result, basically every error in this Wiki article is web-exclusive.

=== Why aren't reports updated automatically in the web? ===

Report updates were historically done by ITrack/Presage desktop, and there is currently no system for automatically updating reports without using desktop. One is in progress, but as of 2/4/2026, it is not ready for primetime.

=== Why do I sometimes get "504 Gateway Timeout" when running a report in web? ===

As outlined above, there are multiple web servers involved in the process of generating a PDF from a Crystal Report in the web, and each one of them has their own server-level timeouts. The web server connecting you to the application API (Chromium, Presage API, EE API) might time you out, and so might the web server connecting the application API to the Crystal Server.

==== Can we make the timeouts longer? ====

The short answer is "not really". Since the timeouts are at the web server level (i.e., nginx/Apache) all requests to that server have the same timeout. We could decide not to time any request out until several minutes have passed, but if a request is taking that long, it ''should'' time out.

=== How is Report Queue, the Python application, involved in this? ===

It's not. Crystal Server and Report Queue are completely separate applications. Crystal Server only generates PDF previews. Report Queue handles printing and emailing reports. Crystal Server is written in Node.js, Report Queue is written in Python. Their main similarity is that they both invoke Report Commander to generate the PDF file, and log to the <code>reportqueue</code> table.

=== Why do Presage customers need set up manually? ===

Presage customers (generally) are on their own VM, and therefore database server. Therefore, they need their own entries in the Crystal Server config file.

Theoretically SMB customers, since they're on the same server, could share a config, but that hasn't been explored as of 2/4/2026.

=== Why do Enterprise customers need set up manually? ===

Enterprise customers are generally on their own VM or server. Additionally, EE customers might not want to use our central server, and might want to host their own. Therefore, they need their own entries in the Crystal Server config file, or their own Crystal Server instance entirely.

=== Why don't Chromium customers need to be set up manually? ===

Since Chromium users are on one of three servers, (except for dev, demo, etc.) all Chromium instances can just use the config for their regional server

== Common Errors (Table Mode) ==

This table will hold the answers to (probably) any error you will encounter running reports in Presage Web

{| class="wikitable" style=""
|+ Common Errors
|-
! style="min-width: 100px;"| Error !! Description !! How to Fix
|-
| Invalid Session. Try logging out and logging back in. || This means that the report server was not able to verify your session. Either your session has expired, or the Crystal Server is not configured for that database. The most likely cause of this is, if logging out and back in doesn't fix it, is that the (generally Presage) customer hasn't been set up on the Crystal Server, or some configuration has changed. || If the config for that customer is missing, then add it matching the template. If it is present, make sure that the Crystal Server and Chromium/Presage API are configured with the same DB URL. Otherwise, check the ODBC connection and DB credentials. Charles can check the logs to double check the URLs are good, as well as update the config file. Brian can then restart the Crystal Server service to load the updated configuration.
|-
| rowspan="5" |Error running report. Double check the report parameters and try again. || This means that Report Commander did not receive the correct amount of parameters for the report. Often times, the report will run fine on desktop, because the Crystal SDK can "fill in the gaps" or ignore extra parameters, while the web Report Viewer cannot, and needs a row in reportparameter for every parameter. Check the <code>Report Viewer > History</code> tab for more error details || Generally, update the report and re-run adders, but '''See Below''' for more details, and check <code>Report Viewer > History</code> for more parameter and error details. If updating the report and adder doesn't fix it, it's possible that they are out of date and need fixed.
|-
| '''"Invalid value for <parameter>"''' means Report Commander received an invalid value for the listed parameter. Usually this just means you forgot to fill a parameter out, but could be caused by by an outdated report / adders. || Make sure all parameters are filled out.
|-
| '''"Parameter not found in report: <parameter>"''' means that a parameter was passed to the report that the report doesn't expect. || If caused by an out-of-date report (more common), update the report. If caused by out-of-date adders, re-run adders.
|-
| '''"Missing parameter values"''' means that the report was not passed all expected parameters. Normally, this is because a parameter was added to the report, and the adders are out of date. || Re-run adders.
|-
| '''"The types of the parameter field and parameter field current values are not compatible"''' means that Crystal was passed a parameter value of the wrong type for that parameter. For example, a string instead of a number || Make sure ITrack is sending parameters of the type the report expects to receive
|-
|| (I can't remember the error message) || Missing / invalid ODBC configuration. I think this presents as "could not connect to the database" or something to that effect. Sometimes it'll give you a "database vendor code" just like ITrack desktop. || Depending on the error code, Brian can make sure the ODBC connection is valid, and give Charles the name to check that the ODBC connection name in the Crystal Server config is correct. But some error codes like 1064 are unrelated to the odbc setup
|-
|| Invalid Report || The Crystal Server failed to find the report with the specified name/type. || Make sure the report exists in the customer database with the given name and type, and a valid <code>report.fileid</code>. In Presage, there used to be a bug where running reports with a non-English language selected would fail with this error.
|-
|| The file or directory is corrupted and unreadable || This would come up every so often because the D drive on Bunnahabhain was failing. It shouldn't happen anymore. || It shouldn't happen again, but if it does, delete the cached report file from <code>M:\report_cache</code> on Bunnahabhain. Maybe reupload the report if it persists after that.
|-
|| Database logon failed || ODBC could not connect to the database || Ask Brian (or maybe someone else from @Systems) to double check the ODBC connection on Bunnahabhain for that customer
|-
|| <code>Database Vendor Code (code)</code> || There was some MySQL error. Look up the error code. || Might depend on the error code, but it's probably because of a bad query in the report. Reupload report. If some parameters are missing or blank, there could have been an issue running a report parameter query, and omitting those parameters could have caused a syntax error (1064)
|-
|| <code>Internal Server Error</code> || You're probably on a version of EEW that doesn't forward the error to the client properly. || Check Report Viewer > History to see the actual error
|}

=== Other Errors ===

<code>Error: WARNING: MYSQL_OPT_RECONNECT is deprecated and will be removed in a future version.</code> - Disable "Auto Reconnect" on ODBC. Presents as "Unkown Error" or "Internal Server Error" in the UI

== Logs ==

The log file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\crystalserverservice.log</code>

A normal log entry for a report job looks like this:

<pre>
Connection created for 'hosteddb-southeast.isoftdata.com.373487'
args [
'-report="D:\\Node\\crystal-reports-server\\cache\\A95AC82D42C7A2A9AFF9F720DA5F3159.rpt"',
'-login!={server:reporting_hosted_southeast}{database:373487}',
'-exportfile="D:\\Node\\crystal-reports-server\\cache\\output\\default_invoice_2024-12-03T19-20-25.872Z.pdf"',
'-exportformat="PDF"',
'-namedparameters invoicenum="5150"'
]
Destroying connection for 'hosteddb-southeast.isoftdata.com.373487'
</pre>

If you see a message like this, then the Crystal Server (not ODBC) failed to connect to the database, and there will probably be a logged request body right below it. The logged request body should have the db host sent from the application, which can be compared to the valid hosts in the config file

<pre>
Destroying connection for 'iceriver.presageanalytics.com.UNKNOWN DATABASE'
</pre>

The most common errors you'll see start like this and will show the command used to run Report Commander as well as a more-detailed error message in a mess of JSON.

<pre>
ReportError: A Report Commander error has occurred
</pre>

== Configuration ==

This will go over how to configure a customer on the Crystal Server, not so much how to deploy and configure a new Crystal Server.

The config file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\config.json</code>

Generally, you just need to set the host, user, password, and odbc data sources for a new connection. However, host MUST be unique, and MUST match the ITrack/Presage server config, as that's what's used to look up the rest of the connection info. Most of the time you can just add another entry to the JSON, like so

<code><pre>{
"host": "HOST",
"user": "USER",
"password": "PASSWORD",
"odbcDataSource": "ODBC DATA SOURCE NAME"
}</pre></code>

In some cases you might also need to set the <code>caPath</code>, <code>certPath</code>, <code>keyPath</code> properties depending on the SSL config. See other configured hosts for examples.

After adding to the JSON, restart the <code>CrystalServer</code> service to apply any changes. See below for more product-specific details.

=== Chromium ===

Does not have to be configured per-customer. One config per VM. The users have more security and so they use more of the SSL options than other users

=== Presage Web/API ===

<code>REPORT_SERVER_URI</code> specifies the report server URI used by the server, and <code>MYSQL_HOST</code> specifies the DB host. <code>EXTERNAL_DB_HOST</code> will be sent to the Crystal Server instead of <code>MYSQL_HOST</code>, if specified. '''Either <code>MYSQL_HOST</code> or <code>EXTERNAL_DB_HOST</code> MUST match the <code>host</code> in the Crystal Server config file or it will not work!'''

==== SMB ====

Currently (12/04/2024), Culligan GI is the only Presage SMB customer, and was configured individually. Maybe in the future, Presage SMB will work like Chromium and just have one config per VM, but that's not currently the case.

Since the setup for SMB clients is slightly different, the <code>MYSQL_HOST</code> is an "internal" IP, but we need an external host that matches what the Crystal Server knows. To get around this, specify this ENV variable:<code>EXTERNAL_DB_HOST: <customername>-database.presageanalytics.com</code>. Make sure the URL matches the one in the Crystal Server config. Apparently, SMB DB URLs will always have <code>-database</code> in them since the SMB docker containers don't run on the same iron as MySQL.

As of 02/03/2025, there's also Bartlett, which had some issues setting it up related to SSL. Brian fixed it, I'm not sure what he did. I think they're also set up slightly differently than Culligan GI

==== Self-Hosted ====

If they're okay hitting our Crystal Server, we just need to make sure that their database can be reached on Bunnahabhain, then the setup is the same as a hosted yard.

If not, we'll have to deploy it to a Windows server they control, and set the <code>REPORT_SERVER_URI</code> ENV variable in the API to the proper URI. Presage API will have to be able to reach <code><The Server URL>/process_report</code> in order to generate the reports

=== Enterprise Web/API ===

If we host the customer, we should just set them up on our Crystal Server. Follow the general steps for configuring them in the Crystal Server config.json, then set some ENV variables in Portainer:

* <code>REPORT_SERVER_URI: http://print.itrackchromium.com</code>
* <code>EXTERNAL_DB_HOST: example-url.itrackenterprise.com</code>

WG, UT&W, & QBT are currently (07/08/25) the only EE customers with the web report viewer on, and they also had to have the caPath set in the crystal server config to the old/not-2024 ca cert. Not sure if that'll be true for other EE customers, but it was for them.

If they're self hosted, and don't want to use our Crystal Server, follow the steps under "Deployment", then set the above ENV variables to the proper values for their setup.

== Updating ==

Not 100% sure since it's been awhile, but I'm pretty sure the process is basically:
1. Build the Crystal Server to an exe again
2. Replace the old exe on BH
3. Restart CrystalServer service

== Deployment ==

For 99% of customers, this section will not apply. But in the event that a self-hosted customer wants to host their own Crystal Server, this is probably how.

* Locate a Windows Server
* Install Report Commander on it
* Run CrystalServerSetup.exe from dl.isoftdata.com, I think this sets up the service to make it run in the background and on startup?
* Get the latest EXE or build a new one from https://github.com/ISoft-Data-Systems/crystal-reports-server and replace the old EXE from the installer
* Restart the CrystalServer service
* Make sure the service is reachable from wherever the Presage API is running
* At this point, they should be able to make a request to <code>serveruri</code>/process_report and get a report back.

== Misc / Notes ==

Housby has Crystal Server deployed to generate invoice PDFs for an ecommerce integration. They're using a version before we compiled it to an exe, so if they ever run into bugs or need an update it will be a little different

Web Report Viewer Troubleshooting

2026-02-12T22:40:29Z

Ckaup: /* How is Report Queue, the Python application, involved in this? */

This article applies to Presage Web and ITrack Chromium. The web Report Viewer will give a general error, error details are logged to the reportqueue table and can be viewed in the "History" (web) or "Print Queue" (desktop) tab of the Report Viewer screen.

== Terms ==

* Crystal Server - the Node.JS application that uses Report Commander to generate the report PDF. Runs on Bunnahabhain. '''This application is not the same as Report Queue.'''
* Report Commander - command line application used to generate report PDFs by the Crystal Server (and Report Queue)
* Report Queue - python application that reads from reportqueue table to send emails and print to a printer. '''Report Queue is separate from Crystal Server, and the two systems do not interact.'''
* reportqueue - a table in the database that logs report runs.
* reportparameter - a table in the database that associates parameters to reports

== FAQ ==

=== How does the web report viewer work? ===

Since we can't run crystal reports directly in the browser, we need to run them on a central server and send them back to the web browser. There are multiple servers involved in this process, which I'll outline below

* The report and parameter list are loaded from the application's API (Chromium, Presage API, EE API)
* The user selects a report, fills out parameters, and clicks "Preview"
* A request is sent to the application backend (Chromium, Presage API, EE API)
* Application backend sends a request to Crystal Server, running on Bunnahabhain, or a customer server if relevant. This requests includes details of the report to run, which database to run it on, and a valid session token for that database.
* Bunnahabhain takes this request, and attempts to validate the given session token in the given database. If this fails, such as if the token is invalid or it can't connect to the database, an "Invalid Session" error is thrown.
* After the session is validated, Crystal Server will download the report file from the customer's database, and run default parameter queries. The report is saved to the "cache directory" specified in the config, with the file's hash as the file name.
* Then, Crystal Server creates a command line string to run Report Commander for the given report and parameters
* Report Commander is then invoked to generate the PDF, connecting to the database with ODBC. The PDF is saved to a folder in the Crystal Server's "cache directory". If Report Commander throws an error, it is forwarded to the application API (Chromium, Presage API, EE API), which saves it to the <code>reportqueue</code> table and forwards that error to the client, where it is displayed.
* If it succeeds, the report file is base64 encoded and sent back to the application API (Chromium, Presage API, EE API), along with the time it took to execute the report.
* The application API receives the request, saves the details to <code>reportqueue</code>/<code>reportqueueparameter</code>, and returns the base64 encoded PDF to the client
* The client receives the response from its backend, and displays the base64 encoded PDF in the browser using an <code><object/></code> tag

==== How is that different from desktop? ====

ITrack desktop talks directly to the Crystal Reports SDK on the individual workstation, instead of sending report jobs to a central server (Bunnahabhain) running Crystal Server.

=== Why can't web work the same way as desktop? ===

Chromium, Presage Web, and Enterprise Web run inside of a web browser, and can therefore be used on multiple operating systems without installing anything. Crystal Reports SDK is Windows-only and requires installation. Therefore, we need a central server to generate the pdf and send it back to the web browser (with some extra steps in between)

=== Why does this report run on desktop, but not on web? ===

As outlined above, web and desktop have entirely different stacks for running crystal reports. In short, web uses Report Commander instead of the Crystal SDK. I don't know exactly how the official Crystal SDK works, but it seems to be more tolerant to being passed extra parameters, or missing parameters. Report Commander is pickier so it will throw when you give it an extra parameter not found in the report, or if you are missing a required parameter value. As a result, basically every error in this Wiki article is web-exclusive.

=== Why aren't reports updated automatically in the web? ===

Report updates were historically done by ITrack/Presage desktop, and there is currently no system for automatically updating reports without using desktop. One is in progress, but as of 2/4/2026, it is not ready for primetime.

=== Why do I sometimes get "504 Gateway Timeout" when running a report in web? ===

As outlined above, there are multiple web servers involved in the process of generating a PDF from a Crystal Report in the web, and each one of them has their own server-level timeouts. The web server connecting you to the application API (Chromium, Presage API, EE API) might time you out, and so might the web server connecting the application API to the Crystal Server.

==== Can we make the timeouts longer? ====

The short answer is "not really". Since the timeouts are at the web server level (i.e., nginx/Apache) all requests to that server have the same timeout. We could decide not to time any request out until several minutes have passed, but if a request is taking that long, it ''should'' time out.

=== How is Report Queue, the Python application, involved in this? ===

It's not. Crystal Server and Report Queue are completely separate applications. Crystal Server only generates PDF previews. Report Queue handles printing and emailing reports. Crystal Server is written in Node.js, Report Queue is written in Python. Their main similarity is that they both invoke Report Commander to generate the PDF file, and log to the <code>reportqueue</code> table.

=== Why do Presage customers need set up manually? ===

Presage customers (generally) are on their own VM, and therefore database server. Therefore, they need their own entries in the Crystal Server config file.

Theoretically SMB customers, since they're on the same server, could share a config, but that hasn't been explored as of 2/4/2026.

=== Why do Enterprise customers need set up manually? ===

Enterprise customers are generally on their own VM or server. Additionally, EE customers might not want to use our central server, and might want to host their own. Therefore, they need their own entries in the Crystal Server config file, or their own Crystal Server instance entirely.

=== Why don't Chromium customers need to be set up manually? ===

Since Chromium users are on one of three servers, (except for dev, demo, etc.) all Chromium instances can just use the config for their regional server

== Common Errors (Table Mode) ==

This table will hold the answers to (probably) any error you will encounter running reports in Presage Web

{| class="wikitable" style=""
|+ Common Errors
|-
! style="min-width: 100px;"| Error !! Description !! How to Fix
|-
| Invalid Session. Try logging out and logging back in. || This means that the report server was not able to verify your session. Either your session has expired, or the Crystal Server is not configured for that database. The most likely cause of this is, if logging out and back in doesn't fix it, is that the (generally Presage) customer hasn't been set up on the Crystal Server, or some configuration has changed. || If the config for that customer is missing, then add it matching the template. If it is present, make sure that the Crystal Server and Chromium/Presage API are configured with the same DB URL. Otherwise, check the ODBC connection and DB credentials. Charles can check the logs to double check the URLs are good, as well as update the config file. Brian can then restart the Crystal Server service to load the updated configuration.
|-
| rowspan="5" |Error running report. Double check the report parameters and try again. || This means that Report Commander did not receive the correct amount of parameters for the report. Often times, the report will run fine on desktop, because the Crystal SDK can "fill in the gaps" or ignore extra parameters, while the web Report Viewer cannot, and needs a row in reportparameter for every parameter. Check the <code>Report Viewer > History</code> tab for more error details || Generally, update the report and re-run adders, but '''See Below''' for more details, and check <code>Report Viewer > History</code> for more parameter and error details. If updating the report and adder doesn't fix it, it's possible that they are out of date and need fixed.
|-
| '''"Invalid value for <parameter>"''' means Report Commander received an invalid value for the listed parameter. Usually this just means you forgot to fill a parameter out, but could be caused by by an outdated report / adders. || Make sure all parameters are filled out.
|-
| '''"Parameter not found in report: <parameter>"''' means that a parameter was passed to the report that the report doesn't expect. || If caused by an out-of-date report (more common), update the report. If caused by out-of-date adders, re-run adders.
|-
| '''"Missing parameter values"''' means that the report was not passed all expected parameters. Normally, this is because a parameter was added to the report, and the adders are out of date. || Re-run adders.
|-
| '''"The types of the parameter field and parameter field current values are not compatible"''' means that Crystal was passed a parameter value of the wrong type for that parameter. For example, a string instead of a number || Make sure ITrack is sending parameters of the type the report expects to receive
|-
|| (I can't remember the error message) || Missing / invalid ODBC configuration. I think this presents as "could not connect to the database" or something to that effect. Sometimes it'll give you a "database vendor code" just like ITrack desktop. || Depending on the error code, Brian can make sure the ODBC connection is valid, and give Charles the name to check that the ODBC connection name in the Crystal Server config is correct. But some error codes like 1064 are unrelated to the odbc setup
|-
|| Invalid Report || The Crystal Server failed to find the report with the specified name/type. || Make sure the report exists in the customer database with the given name and type, and a valid <code>report.fileid</code>. In Presage, there used to be a bug where running reports with a non-English language selected would fail with this error.
|-
|| The file or directory is corrupted and unreadable || This would come up every so often because the D drive on Bunnahabhain was failing. It shouldn't happen anymore. || It shouldn't happen again, but if it does, delete the cached report file from <code>M:\report_cache</code> on Bunnahabhain. Maybe reupload the report if it persists after that.
|-
|| Database logon failed || ODBC could not connect to the database || Ask Brian (or maybe someone else from @Systems) to double check the ODBC connection on Bunnahabhain for that customer
|-
|| <code>Database Vendor Code (code)</code> || There was some MySQL error. Look up the error code. || Might depend on the error code, but it's probably because of a bad query in the report. Reupload report.
|-
|| <code>Internal Server Error</code> || You're probably on a version of EEW that doesn't forward the error to the client properly. || Check Report Viewer > History to see the actual error
|}

=== Other Errors ===

<code>Error: WARNING: MYSQL_OPT_RECONNECT is deprecated and will be removed in a future version.</code> - Disable "Auto Reconnect" on ODBC. Presents as "Unkown Error" or "Internal Server Error" in the UI

== Logs ==

The log file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\crystalserverservice.log</code>

A normal log entry for a report job looks like this:

<pre>
Connection created for 'hosteddb-southeast.isoftdata.com.373487'
args [
'-report="D:\\Node\\crystal-reports-server\\cache\\A95AC82D42C7A2A9AFF9F720DA5F3159.rpt"',
'-login!={server:reporting_hosted_southeast}{database:373487}',
'-exportfile="D:\\Node\\crystal-reports-server\\cache\\output\\default_invoice_2024-12-03T19-20-25.872Z.pdf"',
'-exportformat="PDF"',
'-namedparameters invoicenum="5150"'
]
Destroying connection for 'hosteddb-southeast.isoftdata.com.373487'
</pre>

If you see a message like this, then the Crystal Server (not ODBC) failed to connect to the database, and there will probably be a logged request body right below it. The logged request body should have the db host sent from the application, which can be compared to the valid hosts in the config file

<pre>
Destroying connection for 'iceriver.presageanalytics.com.UNKNOWN DATABASE'
</pre>

The most common errors you'll see start like this and will show the command used to run Report Commander as well as a more-detailed error message in a mess of JSON.

<pre>
ReportError: A Report Commander error has occurred
</pre>

== Configuration ==

This will go over how to configure a customer on the Crystal Server, not so much how to deploy and configure a new Crystal Server.

The config file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\config.json</code>

Generally, you just need to set the host, user, password, and odbc data sources for a new connection. However, host MUST be unique, and MUST match the ITrack/Presage server config, as that's what's used to look up the rest of the connection info. Most of the time you can just add another entry to the JSON, like so

<code><pre>{
"host": "HOST",
"user": "USER",
"password": "PASSWORD",
"odbcDataSource": "ODBC DATA SOURCE NAME"
}</pre></code>

In some cases you might also need to set the <code>caPath</code>, <code>certPath</code>, <code>keyPath</code> properties depending on the SSL config. See other configured hosts for examples.

After adding to the JSON, restart the <code>CrystalServer</code> service to apply any changes. See below for more product-specific details.

=== Chromium ===

Does not have to be configured per-customer. One config per VM. The users have more security and so they use more of the SSL options than other users

=== Presage Web/API ===

<code>REPORT_SERVER_URI</code> specifies the report server URI used by the server, and <code>MYSQL_HOST</code> specifies the DB host. <code>EXTERNAL_DB_HOST</code> will be sent to the Crystal Server instead of <code>MYSQL_HOST</code>, if specified. '''Either <code>MYSQL_HOST</code> or <code>EXTERNAL_DB_HOST</code> MUST match the <code>host</code> in the Crystal Server config file or it will not work!'''

==== SMB ====

Currently (12/04/2024), Culligan GI is the only Presage SMB customer, and was configured individually. Maybe in the future, Presage SMB will work like Chromium and just have one config per VM, but that's not currently the case.

Since the setup for SMB clients is slightly different, the <code>MYSQL_HOST</code> is an "internal" IP, but we need an external host that matches what the Crystal Server knows. To get around this, specify this ENV variable:<code>EXTERNAL_DB_HOST: <customername>-database.presageanalytics.com</code>. Make sure the URL matches the one in the Crystal Server config. Apparently, SMB DB URLs will always have <code>-database</code> in them since the SMB docker containers don't run on the same iron as MySQL.

As of 02/03/2025, there's also Bartlett, which had some issues setting it up related to SSL. Brian fixed it, I'm not sure what he did. I think they're also set up slightly differently than Culligan GI

==== Self-Hosted ====

If they're okay hitting our Crystal Server, we just need to make sure that their database can be reached on Bunnahabhain, then the setup is the same as a hosted yard.

If not, we'll have to deploy it to a Windows server they control, and set the <code>REPORT_SERVER_URI</code> ENV variable in the API to the proper URI. Presage API will have to be able to reach <code><The Server URL>/process_report</code> in order to generate the reports

=== Enterprise Web/API ===

If we host the customer, we should just set them up on our Crystal Server. Follow the general steps for configuring them in the Crystal Server config.json, then set some ENV variables in Portainer:

* <code>REPORT_SERVER_URI: http://print.itrackchromium.com</code>
* <code>EXTERNAL_DB_HOST: example-url.itrackenterprise.com</code>

WG, UT&W, & QBT are currently (07/08/25) the only EE customers with the web report viewer on, and they also had to have the caPath set in the crystal server config to the old/not-2024 ca cert. Not sure if that'll be true for other EE customers, but it was for them.

If they're self hosted, and don't want to use our Crystal Server, follow the steps under "Deployment", then set the above ENV variables to the proper values for their setup.

== Updating ==

Not 100% sure since it's been awhile, but I'm pretty sure the process is basically:
1. Build the Crystal Server to an exe again
2. Replace the old exe on BH
3. Restart CrystalServer service

== Deployment ==

For 99% of customers, this section will not apply. But in the event that a self-hosted customer wants to host their own Crystal Server, this is probably how.

* Locate a Windows Server
* Install Report Commander on it
* Run CrystalServerSetup.exe from dl.isoftdata.com, I think this sets up the service to make it run in the background and on startup?
* Get the latest EXE or build a new one from https://github.com/ISoft-Data-Systems/crystal-reports-server and replace the old EXE from the installer
* Restart the CrystalServer service
* Make sure the service is reachable from wherever the Presage API is running
* At this point, they should be able to make a request to <code>serveruri</code>/process_report and get a report back.

== Misc / Notes ==

Housby has Crystal Server deployed to generate invoice PDFs for an ecommerce integration. They're using a version before we compiled it to an exe, so if they ever run into bugs or need an update it will be a little different

Web Report Viewer Troubleshooting

2026-02-04T18:09:10Z

Ckaup: /* FAQ */

This article applies to Presage Web and ITrack Chromium. The web Report Viewer will give a general error, error details are logged to the reportqueue table and can be viewed in the "History" (web) or "Print Queue" (desktop) tab of the Report Viewer screen.

== Terms ==

* Crystal Server - the Node.JS application that uses Report Commander to generate the report PDF. Runs on Bunnahabhain. '''This application is not the same as Report Queue.'''
* Report Commander - command line application used to generate report PDFs by the Crystal Server (and Report Queue)
* Report Queue - python application that reads from reportqueue table to send emails and print to a printer. '''Report Queue is separate from Crystal Server, and the two systems do not interact.'''
* reportqueue - a table in the database that logs report runs.
* reportparameter - a table in the database that associates parameters to reports

== FAQ ==

=== How does the web report viewer work? ===

Since we can't run crystal reports directly in the browser, we need to run them on a central server and send them back to the web browser. There are multiple servers involved in this process, which I'll outline below

* The report and parameter list are loaded from the application's API (Chromium, Presage API, EE API)
* The user selects a report, fills out parameters, and clicks "Preview"
* A request is sent to the application backend (Chromium, Presage API, EE API)
* Application backend sends a request to Crystal Server, running on Bunnahabhain, or a customer server if relevant. This requests includes details of the report to run, which database to run it on, and a valid session token for that database.
* Bunnahabhain takes this request, and attempts to validate the given session token in the given database. If this fails, such as if the token is invalid or it can't connect to the database, an "Invalid Session" error is thrown.
* After the session is validated, Crystal Server will download the report file from the customer's database, and run default parameter queries. The report is saved to the "cache directory" specified in the config, with the file's hash as the file name.
* Then, Crystal Server creates a command line string to run Report Commander for the given report and parameters
* Report Commander is then invoked to generate the PDF, connecting to the database with ODBC. The PDF is saved to a folder in the Crystal Server's "cache directory". If Report Commander throws an error, it is forwarded to the application API (Chromium, Presage API, EE API), which saves it to the <code>reportqueue</code> table and forwards that error to the client, where it is displayed.
* If it succeeds, the report file is base64 encoded and sent back to the application API (Chromium, Presage API, EE API), along with the time it took to execute the report.
* The application API receives the request, saves the details to <code>reportqueue</code>/<code>reportqueueparameter</code>, and returns the base64 encoded PDF to the client
* The client receives the response from its backend, and displays the base64 encoded PDF in the browser using an <code><object/></code> tag

==== How is that different from desktop? ====

ITrack desktop talks directly to the Crystal Reports SDK on the individual workstation, instead of sending report jobs to a central server (Bunnahabhain) running Crystal Server.

=== Why can't web work the same way as desktop? ===

Chromium, Presage Web, and Enterprise Web run inside of a web browser, and can therefore be used on multiple operating systems without installing anything. Crystal Reports SDK is Windows-only and requires installation. Therefore, we need a central server to generate the pdf and send it back to the web browser (with some extra steps in between)

=== Why does this report run on desktop, but not on web? ===

As outlined above, web and desktop have entirely different stacks for running crystal reports. In short, web uses Report Commander instead of the Crystal SDK. I don't know exactly how the official Crystal SDK works, but it seems to be more tolerant to being passed extra parameters, or missing parameters. Report Commander is pickier so it will throw when you give it an extra parameter not found in the report, or if you are missing a required parameter value. As a result, basically every error in this Wiki article is web-exclusive.

=== Why aren't reports updated automatically in the web? ===

Report updates were historically done by ITrack/Presage desktop, and there is currently no system for automatically updating reports without using desktop. One is in progress, but as of 2/4/2026, it is not ready for primetime.

=== Why do I sometimes get "504 Gateway Timeout" when running a report in web? ===

As outlined above, there are multiple web servers involved in the process of generating a PDF from a Crystal Report in the web, and each one of them has their own server-level timeouts. The web server connecting you to the application API (Chromium, Presage API, EE API) might time you out, and so might the web server connecting the application API to the Crystal Server.

==== Can we make the timeouts longer? ====

The short answer is "not really". Since the timeouts are at the web server level (i.e., nginx/Apache) all requests to that server have the same timeout. We could decide not to time any request out until several minutes have passed, but if a request is taking that long, it ''should'' time out.

=== How is Report Queue, the Python application, involved in this? ===

It's not. Crystal Server and Report Queue are completely separate applications. Crystal Server only generates PDF previews. Report Queue handles printing and emailing reports. Crystal Server is written in Node.js, Report Queue is written in Python. Their main similarity is that they both invoke Report Commander to generate the PDF file.

=== Why do Presage customers need set up manually? ===

Presage customers (generally) are on their own VM, and therefore database server. Therefore, they need their own entries in the Crystal Server config file.

Theoretically SMB customers, since they're on the same server, could share a config, but that hasn't been explored as of 2/4/2026.

=== Why do Enterprise customers need set up manually? ===

Enterprise customers are generally on their own VM or server. Additionally, EE customers might not want to use our central server, and might want to host their own. Therefore, they need their own entries in the Crystal Server config file, or their own Crystal Server instance entirely.

=== Why don't Chromium customers need to be set up manually? ===

Since Chromium users are on one of three servers, (except for dev, demo, etc.) all Chromium instances can just use the config for their regional server

== Common Errors (Table Mode) ==

This table will hold the answers to (probably) any error you will encounter running reports in Presage Web

{| class="wikitable" style=""
|+ Common Errors
|-
! style="min-width: 100px;"| Error !! Description !! How to Fix
|-
| Invalid Session. Try logging out and logging back in. || This means that the report server was not able to verify your session. Either your session has expired, or the Crystal Server is not configured for that database. The most likely cause of this is, if logging out and back in doesn't fix it, is that the (generally Presage) customer hasn't been set up on the Crystal Server, or some configuration has changed. || If the config for that customer is missing, then add it matching the template. If it is present, make sure that the Crystal Server and Chromium/Presage API are configured with the same DB URL. Otherwise, check the ODBC connection and DB credentials. Charles can check the logs to double check the URLs are good, as well as update the config file. Brian can then restart the Crystal Server service to load the updated configuration.
|-
| rowspan="5" |Error running report. Double check the report parameters and try again. || This means that Report Commander did not receive the correct amount of parameters for the report. Often times, the report will run fine on desktop, because the Crystal SDK can "fill in the gaps" or ignore extra parameters, while the web Report Viewer cannot, and needs a row in reportparameter for every parameter. Check the <code>Report Viewer > History</code> tab for more error details || Generally, update the report and re-run adders, but '''See Below''' for more details, and check <code>Report Viewer > History</code> for more parameter and error details. If updating the report and adder doesn't fix it, it's possible that they are out of date and need fixed.
|-
| '''"Invalid value for <parameter>"''' means Report Commander received an invalid value for the listed parameter. Usually this just means you forgot to fill a parameter out, but could be caused by by an outdated report / adders. || Make sure all parameters are filled out.
|-
| '''"Parameter not found in report: <parameter>"''' means that a parameter was passed to the report that the report doesn't expect. || If caused by an out-of-date report (more common), update the report. If caused by out-of-date adders, re-run adders.
|-
| '''"Missing parameter values"''' means that the report was not passed all expected parameters. Normally, this is because a parameter was added to the report, and the adders are out of date. || Re-run adders.
|-
| '''"The types of the parameter field and parameter field current values are not compatible"''' means that Crystal was passed a parameter value of the wrong type for that parameter. For example, a string instead of a number || Make sure ITrack is sending parameters of the type the report expects to receive
|-
|| (I can't remember the error message) || Missing / invalid ODBC configuration. I think this presents as "could not connect to the database" or something to that effect. Sometimes it'll give you a "database vendor code" just like ITrack desktop. || Depending on the error code, Brian can make sure the ODBC connection is valid, and give Charles the name to check that the ODBC connection name in the Crystal Server config is correct. But some error codes like 1064 are unrelated to the odbc setup
|-
|| Invalid Report || The Crystal Server failed to find the report with the specified name/type. || Make sure the report exists in the customer database with the given name and type, and a valid <code>report.fileid</code>. In Presage, there used to be a bug where running reports with a non-English language selected would fail with this error.
|-
|| The file or directory is corrupted and unreadable || This would come up every so often because the D drive on Bunnahabhain was failing. It shouldn't happen anymore. || It shouldn't happen again, but if it does, delete the cached report file from <code>M:\report_cache</code> on Bunnahabhain. Maybe reupload the report if it persists after that.
|-
|| Database logon failed || ODBC could not connect to the database || Ask Brian (or maybe someone else from @Systems) to double check the ODBC connection on Bunnahabhain for that customer
|-
|| <code>Database Vendor Code (code)</code> || There was some MySQL error. Look up the error code. || Might depend on the error code, but it's probably because of a bad query in the report. Reupload report.
|-
|| <code>Internal Server Error</code> || You're probably on a version of EEW that doesn't forward the error to the client properly. || Check Report Viewer > History to see the actual error
|}

=== Other Errors ===

<code>Error: WARNING: MYSQL_OPT_RECONNECT is deprecated and will be removed in a future version.</code> - Disable "Auto Reconnect" on ODBC. Presents as "Unkown Error" or "Internal Server Error" in the UI

== Logs ==

The log file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\crystalserverservice.log</code>

A normal log entry for a report job looks like this:

<pre>
Connection created for 'hosteddb-southeast.isoftdata.com.373487'
args [
'-report="D:\\Node\\crystal-reports-server\\cache\\A95AC82D42C7A2A9AFF9F720DA5F3159.rpt"',
'-login!={server:reporting_hosted_southeast}{database:373487}',
'-exportfile="D:\\Node\\crystal-reports-server\\cache\\output\\default_invoice_2024-12-03T19-20-25.872Z.pdf"',
'-exportformat="PDF"',
'-namedparameters invoicenum="5150"'
]
Destroying connection for 'hosteddb-southeast.isoftdata.com.373487'
</pre>

If you see a message like this, then the Crystal Server (not ODBC) failed to connect to the database, and there will probably be a logged request body right below it. The logged request body should have the db host sent from the application, which can be compared to the valid hosts in the config file

<pre>
Destroying connection for 'iceriver.presageanalytics.com.UNKNOWN DATABASE'
</pre>

The most common errors you'll see start like this and will show the command used to run Report Commander as well as a more-detailed error message in a mess of JSON.

<pre>
ReportError: A Report Commander error has occurred
</pre>

== Configuration ==

This will go over how to configure a customer on the Crystal Server, not so much how to deploy and configure a new Crystal Server.

The config file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\config.json</code>

Generally, you just need to set the host, user, password, and odbc data sources for a new connection. However, host MUST be unique, and MUST match the ITrack/Presage server config, as that's what's used to look up the rest of the connection info. Most of the time you can just add another entry to the JSON, like so

<code><pre>{
"host": "HOST",
"user": "USER",
"password": "PASSWORD",
"odbcDataSource": "ODBC DATA SOURCE NAME"
}</pre></code>

In some cases you might also need to set the <code>caPath</code>, <code>certPath</code>, <code>keyPath</code> properties depending on the SSL config. See other configured hosts for examples.

After adding to the JSON, restart the <code>CrystalServer</code> service to apply any changes. See below for more product-specific details.

=== Chromium ===

Does not have to be configured per-customer. One config per VM. The users have more security and so they use more of the SSL options than other users

=== Presage Web/API ===

<code>REPORT_SERVER_URI</code> specifies the report server URI used by the server, and <code>MYSQL_HOST</code> specifies the DB host. <code>EXTERNAL_DB_HOST</code> will be sent to the Crystal Server instead of <code>MYSQL_HOST</code>, if specified. '''Either <code>MYSQL_HOST</code> or <code>EXTERNAL_DB_HOST</code> MUST match the <code>host</code> in the Crystal Server config file or it will not work!'''

==== SMB ====

Currently (12/04/2024), Culligan GI is the only Presage SMB customer, and was configured individually. Maybe in the future, Presage SMB will work like Chromium and just have one config per VM, but that's not currently the case.

Since the setup for SMB clients is slightly different, the <code>MYSQL_HOST</code> is an "internal" IP, but we need an external host that matches what the Crystal Server knows. To get around this, specify this ENV variable:<code>EXTERNAL_DB_HOST: <customername>-database.presageanalytics.com</code>. Make sure the URL matches the one in the Crystal Server config. Apparently, SMB DB URLs will always have <code>-database</code> in them since the SMB docker containers don't run on the same iron as MySQL.

As of 02/03/2025, there's also Bartlett, which had some issues setting it up related to SSL. Brian fixed it, I'm not sure what he did. I think they're also set up slightly differently than Culligan GI

==== Self-Hosted ====

If they're okay hitting our Crystal Server, we just need to make sure that their database can be reached on Bunnahabhain, then the setup is the same as a hosted yard.

If not, we'll have to deploy it to a Windows server they control, and set the <code>REPORT_SERVER_URI</code> ENV variable in the API to the proper URI. Presage API will have to be able to reach <code><The Server URL>/process_report</code> in order to generate the reports

=== Enterprise Web/API ===

If we host the customer, we should just set them up on our Crystal Server. Follow the general steps for configuring them in the Crystal Server config.json, then set some ENV variables in Portainer:

* <code>REPORT_SERVER_URI: http://print.itrackchromium.com</code>
* <code>EXTERNAL_DB_HOST: example-url.itrackenterprise.com</code>

WG, UT&W, & QBT are currently (07/08/25) the only EE customers with the web report viewer on, and they also had to have the caPath set in the crystal server config to the old/not-2024 ca cert. Not sure if that'll be true for other EE customers, but it was for them.

If they're self hosted, and don't want to use our Crystal Server, follow the steps under "Deployment", then set the above ENV variables to the proper values for their setup.

== Updating ==

Not 100% sure since it's been awhile, but I'm pretty sure the process is basically:
1. Build the Crystal Server to an exe again
2. Replace the old exe on BH
3. Restart CrystalServer service

== Deployment ==

For 99% of customers, this section will not apply. But in the event that a self-hosted customer wants to host their own Crystal Server, this is probably how.

* Locate a Windows Server
* Install Report Commander on it
* Run CrystalServerSetup.exe from dl.isoftdata.com, I think this sets up the service to make it run in the background and on startup?
* Get the latest EXE or build a new one from https://github.com/ISoft-Data-Systems/crystal-reports-server and replace the old EXE from the installer
* Restart the CrystalServer service
* Make sure the service is reachable from wherever the Presage API is running
* At this point, they should be able to make a request to <code>serveruri</code>/process_report and get a report back.

== Misc / Notes ==

Housby has Crystal Server deployed to generate invoice PDFs for an ecommerce integration. They're using a version before we compiled it to an exe, so if they ever run into bugs or need an update it will be a little different

Web Report Viewer Troubleshooting

2026-02-04T18:07:51Z

Ckaup: /* FAQ */

This article applies to Presage Web and ITrack Chromium. The web Report Viewer will give a general error, error details are logged to the reportqueue table and can be viewed in the "History" (web) or "Print Queue" (desktop) tab of the Report Viewer screen.

== Terms ==

* Crystal Server - the Node.JS application that uses Report Commander to generate the report PDF. Runs on Bunnahabhain. '''This application is not the same as Report Queue.'''
* Report Commander - command line application used to generate report PDFs by the Crystal Server (and Report Queue)
* Report Queue - python application that reads from reportqueue table to send emails and print to a printer. '''Report Queue is separate from Crystal Server, and the two systems do not interact.'''
* reportqueue - a table in the database that logs report runs.
* reportparameter - a table in the database that associates parameters to reports

== FAQ ==

=== How does the web report viewer work? ===

Since we can't run crystal reports directly in the browser, we need to run them on a central server and send them back to the web browser. There are multiple servers involved in this process, which I'll outline below

* The report and parameter list are loaded from the application's API (Chromium, Presage API, EE API)
* The user selects a report, fills out parameters, and clicks "Preview"
* A request is sent to the application backend (Chromium, Presage API, EE API)
* Application backend sends a request to Crystal Server, running on Bunnahabhain, or a customer server if relevant. This requests includes details of the report to run, which database to run it on, and a valid session token for that database.
* Bunnahabhain takes this request, and attempts to validate the given session token in the given database. If this fails, such as if the token is invalid or it can't connect to the database, an "Invalid Session" error is thrown.
* After the session is validated, Crystal Server will download the report file from the customer's database, and run default parameter queries. The report is saved to the "cache directory" specified in the config, with the file's hash as the file name.
* Then, Crystal Server creates a command line string to run Report Commander for the given report and parameters
* Report Commander is then invoked to generate the PDF, connecting to the database with ODBC. The PDF is saved to a folder in the Crystal Server's "cache directory". If Report Commander throws an error, it is forwarded to the application API (Chromium, Presage API, EE API), which saves it to the <code>reportqueue</code> table and forwards that error to the client, where it is displayed.
* If it succeeds, the report file is base64 encoded and sent back to the application API (Chromium, Presage API, EE API), along with the time it took to execute the report.
* The application API receives the request, saves the details to <code>reportqueue</code>/<code>reportqueueparameter</code>, and returns the base64 encoded PDF to the client
* The client receives the response from its backend, and displays the base64 encoded PDF in the browser using an <code><object/></code> tag

==== How is that different from desktop? ====

ITrack desktop talks directly to the Crystal Reports SDK on the individual workstation, instead of sending report jobs to a central server (Bunnahabhain) running Crystal Server.

=== Why can't web work the same way as desktop? ===

Chromium, Presage Web, and Enterprise Web run inside of a web browser, and can therefore be used on multiple operating systems without installing anything. Crystal Reports SDK is Windows-only and requires installation. Therefore, we need a central server to generate the pdf and send it back to the web browser (with some extra steps in between)

=== Why does this report run on desktop, but not on web? ===

As outlined above, web and desktop have entirely different stacks for running crystal reports. In short, web uses Report Commander instead of the Crystal SDK. I don't know exactly how the official Crystal SDK works, but it seems to be more tolerant to being passed extra parameters, or missing parameters. Report Commander is pickier so it will throw when you give it an extra parameter not found in the report, or if you are missing a required parameter value. As a result, basically every error in this Wiki article is web-exclusive.

=== Why do I sometimes get "504 Gateway Timeout" when running a report in web? ===

As outlined above, there are multiple web servers involved in the process of generating a PDF from a Crystal Report in the web, and each one of them has their own server-level timeouts. The web server connecting you to the application API (Chromium, Presage API, EE API) might time you out, and so might the web server connecting the application API to the Crystal Server.

==== Can we make the timeouts longer? ====

The short answer is "not really". Since the timeouts are at the web server level (i.e., nginx/Apache) all requests to that server have the same timeout. We could decide not to time any request out until several minutes have passed, but if a request is taking that long, it ''should'' time out.

=== How is Report Queue, the Python application, involved in this? ===

It's not. Crystal Server and Report Queue are completely separate applications. Crystal Server only generates PDF previews. Report Queue handles printing and emailing reports. Crystal Server is written in Node.js, Report Queue is written in Python. Their main similarity is that they both invoke Report Commander to generate the PDF file.

=== Why do Presage customers need set up manually? ===

Presage customers (generally) are on their own VM, and therefore database server. Therefore, they need their own entries in the Crystal Server config file.

Theoretically SMB customers, since they're on the same server, could share a config, but that hasn't been explored as of 2/4/2026.

=== Why do Enterprise customers need set up manually? ===

Enterprise customers are generally on their own VM or server. Additionally, EE customers might not want to use our central server, and might want to host their own. Therefore, they need their own entries in the Crystal Server config file, or their own Crystal Server instance entirely.

=== Why don't Chromium customers need to be set up manually? ===

Since Chromium users are on one of three servers, (except for dev, demo, etc.) all Chromium instances can just use the config for their regional server

== Common Errors (Table Mode) ==

This table will hold the answers to (probably) any error you will encounter running reports in Presage Web

{| class="wikitable" style=""
|+ Common Errors
|-
! style="min-width: 100px;"| Error !! Description !! How to Fix
|-
| Invalid Session. Try logging out and logging back in. || This means that the report server was not able to verify your session. Either your session has expired, or the Crystal Server is not configured for that database. The most likely cause of this is, if logging out and back in doesn't fix it, is that the (generally Presage) customer hasn't been set up on the Crystal Server, or some configuration has changed. || If the config for that customer is missing, then add it matching the template. If it is present, make sure that the Crystal Server and Chromium/Presage API are configured with the same DB URL. Otherwise, check the ODBC connection and DB credentials. Charles can check the logs to double check the URLs are good, as well as update the config file. Brian can then restart the Crystal Server service to load the updated configuration.
|-
| rowspan="5" |Error running report. Double check the report parameters and try again. || This means that Report Commander did not receive the correct amount of parameters for the report. Often times, the report will run fine on desktop, because the Crystal SDK can "fill in the gaps" or ignore extra parameters, while the web Report Viewer cannot, and needs a row in reportparameter for every parameter. Check the <code>Report Viewer > History</code> tab for more error details || Generally, update the report and re-run adders, but '''See Below''' for more details, and check <code>Report Viewer > History</code> for more parameter and error details. If updating the report and adder doesn't fix it, it's possible that they are out of date and need fixed.
|-
| '''"Invalid value for <parameter>"''' means Report Commander received an invalid value for the listed parameter. Usually this just means you forgot to fill a parameter out, but could be caused by by an outdated report / adders. || Make sure all parameters are filled out.
|-
| '''"Parameter not found in report: <parameter>"''' means that a parameter was passed to the report that the report doesn't expect. || If caused by an out-of-date report (more common), update the report. If caused by out-of-date adders, re-run adders.
|-
| '''"Missing parameter values"''' means that the report was not passed all expected parameters. Normally, this is because a parameter was added to the report, and the adders are out of date. || Re-run adders.
|-
| '''"The types of the parameter field and parameter field current values are not compatible"''' means that Crystal was passed a parameter value of the wrong type for that parameter. For example, a string instead of a number || Make sure ITrack is sending parameters of the type the report expects to receive
|-
|| (I can't remember the error message) || Missing / invalid ODBC configuration. I think this presents as "could not connect to the database" or something to that effect. Sometimes it'll give you a "database vendor code" just like ITrack desktop. || Depending on the error code, Brian can make sure the ODBC connection is valid, and give Charles the name to check that the ODBC connection name in the Crystal Server config is correct. But some error codes like 1064 are unrelated to the odbc setup
|-
|| Invalid Report || The Crystal Server failed to find the report with the specified name/type. || Make sure the report exists in the customer database with the given name and type, and a valid <code>report.fileid</code>. In Presage, there used to be a bug where running reports with a non-English language selected would fail with this error.
|-
|| The file or directory is corrupted and unreadable || This would come up every so often because the D drive on Bunnahabhain was failing. It shouldn't happen anymore. || It shouldn't happen again, but if it does, delete the cached report file from <code>M:\report_cache</code> on Bunnahabhain. Maybe reupload the report if it persists after that.
|-
|| Database logon failed || ODBC could not connect to the database || Ask Brian (or maybe someone else from @Systems) to double check the ODBC connection on Bunnahabhain for that customer
|-
|| <code>Database Vendor Code (code)</code> || There was some MySQL error. Look up the error code. || Might depend on the error code, but it's probably because of a bad query in the report. Reupload report.
|-
|| <code>Internal Server Error</code> || You're probably on a version of EEW that doesn't forward the error to the client properly. || Check Report Viewer > History to see the actual error
|}

=== Other Errors ===

<code>Error: WARNING: MYSQL_OPT_RECONNECT is deprecated and will be removed in a future version.</code> - Disable "Auto Reconnect" on ODBC. Presents as "Unkown Error" or "Internal Server Error" in the UI

== Logs ==

The log file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\crystalserverservice.log</code>

A normal log entry for a report job looks like this:

<pre>
Connection created for 'hosteddb-southeast.isoftdata.com.373487'
args [
'-report="D:\\Node\\crystal-reports-server\\cache\\A95AC82D42C7A2A9AFF9F720DA5F3159.rpt"',
'-login!={server:reporting_hosted_southeast}{database:373487}',
'-exportfile="D:\\Node\\crystal-reports-server\\cache\\output\\default_invoice_2024-12-03T19-20-25.872Z.pdf"',
'-exportformat="PDF"',
'-namedparameters invoicenum="5150"'
]
Destroying connection for 'hosteddb-southeast.isoftdata.com.373487'
</pre>

If you see a message like this, then the Crystal Server (not ODBC) failed to connect to the database, and there will probably be a logged request body right below it. The logged request body should have the db host sent from the application, which can be compared to the valid hosts in the config file

<pre>
Destroying connection for 'iceriver.presageanalytics.com.UNKNOWN DATABASE'
</pre>

The most common errors you'll see start like this and will show the command used to run Report Commander as well as a more-detailed error message in a mess of JSON.

<pre>
ReportError: A Report Commander error has occurred
</pre>

== Configuration ==

This will go over how to configure a customer on the Crystal Server, not so much how to deploy and configure a new Crystal Server.

The config file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\config.json</code>

Generally, you just need to set the host, user, password, and odbc data sources for a new connection. However, host MUST be unique, and MUST match the ITrack/Presage server config, as that's what's used to look up the rest of the connection info. Most of the time you can just add another entry to the JSON, like so

<code><pre>{
"host": "HOST",
"user": "USER",
"password": "PASSWORD",
"odbcDataSource": "ODBC DATA SOURCE NAME"
}</pre></code>

In some cases you might also need to set the <code>caPath</code>, <code>certPath</code>, <code>keyPath</code> properties depending on the SSL config. See other configured hosts for examples.

After adding to the JSON, restart the <code>CrystalServer</code> service to apply any changes. See below for more product-specific details.

=== Chromium ===

Does not have to be configured per-customer. One config per VM. The users have more security and so they use more of the SSL options than other users

=== Presage Web/API ===

<code>REPORT_SERVER_URI</code> specifies the report server URI used by the server, and <code>MYSQL_HOST</code> specifies the DB host. <code>EXTERNAL_DB_HOST</code> will be sent to the Crystal Server instead of <code>MYSQL_HOST</code>, if specified. '''Either <code>MYSQL_HOST</code> or <code>EXTERNAL_DB_HOST</code> MUST match the <code>host</code> in the Crystal Server config file or it will not work!'''

==== SMB ====

Currently (12/04/2024), Culligan GI is the only Presage SMB customer, and was configured individually. Maybe in the future, Presage SMB will work like Chromium and just have one config per VM, but that's not currently the case.

Since the setup for SMB clients is slightly different, the <code>MYSQL_HOST</code> is an "internal" IP, but we need an external host that matches what the Crystal Server knows. To get around this, specify this ENV variable:<code>EXTERNAL_DB_HOST: <customername>-database.presageanalytics.com</code>. Make sure the URL matches the one in the Crystal Server config. Apparently, SMB DB URLs will always have <code>-database</code> in them since the SMB docker containers don't run on the same iron as MySQL.

As of 02/03/2025, there's also Bartlett, which had some issues setting it up related to SSL. Brian fixed it, I'm not sure what he did. I think they're also set up slightly differently than Culligan GI

==== Self-Hosted ====

If they're okay hitting our Crystal Server, we just need to make sure that their database can be reached on Bunnahabhain, then the setup is the same as a hosted yard.

If not, we'll have to deploy it to a Windows server they control, and set the <code>REPORT_SERVER_URI</code> ENV variable in the API to the proper URI. Presage API will have to be able to reach <code><The Server URL>/process_report</code> in order to generate the reports

=== Enterprise Web/API ===

If we host the customer, we should just set them up on our Crystal Server. Follow the general steps for configuring them in the Crystal Server config.json, then set some ENV variables in Portainer:

* <code>REPORT_SERVER_URI: http://print.itrackchromium.com</code>
* <code>EXTERNAL_DB_HOST: example-url.itrackenterprise.com</code>

WG, UT&W, & QBT are currently (07/08/25) the only EE customers with the web report viewer on, and they also had to have the caPath set in the crystal server config to the old/not-2024 ca cert. Not sure if that'll be true for other EE customers, but it was for them.

If they're self hosted, and don't want to use our Crystal Server, follow the steps under "Deployment", then set the above ENV variables to the proper values for their setup.

== Updating ==

Not 100% sure since it's been awhile, but I'm pretty sure the process is basically:
1. Build the Crystal Server to an exe again
2. Replace the old exe on BH
3. Restart CrystalServer service

== Deployment ==

For 99% of customers, this section will not apply. But in the event that a self-hosted customer wants to host their own Crystal Server, this is probably how.

* Locate a Windows Server
* Install Report Commander on it
* Run CrystalServerSetup.exe from dl.isoftdata.com, I think this sets up the service to make it run in the background and on startup?
* Get the latest EXE or build a new one from https://github.com/ISoft-Data-Systems/crystal-reports-server and replace the old EXE from the installer
* Restart the CrystalServer service
* Make sure the service is reachable from wherever the Presage API is running
* At this point, they should be able to make a request to <code>serveruri</code>/process_report and get a report back.

== Misc / Notes ==

Housby has Crystal Server deployed to generate invoice PDFs for an ecommerce integration. They're using a version before we compiled it to an exe, so if they ever run into bugs or need an update it will be a little different

Web Report Viewer Troubleshooting

2026-02-04T18:03:58Z

Ckaup: /* FAQ */

This article applies to Presage Web and ITrack Chromium. The web Report Viewer will give a general error, error details are logged to the reportqueue table and can be viewed in the "History" (web) or "Print Queue" (desktop) tab of the Report Viewer screen.

== Terms ==

* Crystal Server - the Node.JS application that uses Report Commander to generate the report PDF. Runs on Bunnahabhain. '''This application is not the same as Report Queue.'''
* Report Commander - command line application used to generate report PDFs by the Crystal Server (and Report Queue)
* Report Queue - python application that reads from reportqueue table to send emails and print to a printer. '''Report Queue is separate from Crystal Server, and the two systems do not interact.'''
* reportqueue - a table in the database that logs report runs.
* reportparameter - a table in the database that associates parameters to reports

== FAQ ==

=== How does the web report viewer work? ===

Since we can't run crystal reports directly in the browser, we need to run them on a central server and send them back to the web browser. There are multiple servers involved in this process, which I'll outline below

* The report and parameter list are loaded from the application's API (Chromium, Presage API, EE API)
* The user selects a report, fills out parameters, and clicks "Preview"
* A request is sent to the application backend (Chromium, Presage API, EE API)
* Application backend sends a request to Crystal Server, running on Bunnahabhain, or a customer server if relevant. This requests includes details of the report to run, which database to run it on, and a valid session token for that database.
* Bunnahabhain takes this request, and attempts to validate the given session token in the given database. If this fails, such as if the token is invalid or it can't connect to the database, an "Invalid Session" error is thrown.
* After the session is validated, Crystal Server will download the report file from the customer's database, and run default parameter queries. The report is saved to the "cache directory" specified in the config, with the file's hash as the file name.
* Then, Crystal Server creates a command line string to run Report Commander for the given report and parameters
* Report Commander is then invoked to generate the PDF, connecting to the database with ODBC. The PDF is saved to a folder in the Crystal Server's "cache directory". If Report Commander throws an error, it is forwarded to the application API (Chromium, Presage API, EE API), which saves it to the <code>reportqueue</code> table and forwards that error to the client, where it is displayed.
* If it succeeds, the report file is base64 encoded and sent back to the application API (Chromium, Presage API, EE API), along with the time it took to execute the report.
* The application API receives the request, saves the details to <code>reportqueue</code>/<code>reportqueueparameter</code>, and returns the base64 encoded PDF to the client
* The client receives the response from its backend, and displays the base64 encoded PDF in the browser using an <code><object/></code> tag

==== How is that different from desktop? ====

ITrack desktop talks directly to the Crystal Reports SDK on the individual workstation, instead of sending report jobs to a central server (Bunnahabhain) running Crystal Server.

=== Why can't web work the same way as desktop? ===

Chromium, Presage Web, and Enterprise Web run inside of a web browser, and can therefore be used on multiple operating systems without installing anything. Crystal Reports SDK is Windows-only and requires installation. Therefore, we need a central server to generate the pdf and send it back to the web browser (with some extra steps in between)

=== Why does this report run on desktop, but not on web? ===

As outlined above, web and desktop have entirely different stacks for running crystal reports. In short, web uses Report Commander instead of the Crystal SDK. I don't know exactly how the official Crystal SDK works, but it seems to be more tolerant to being passed extra parameters, or missing parameters. Report Commander is pickier so it will throw when you give it an extra parameter not found in the report, or if you are missing a required parameter value. As a result, basically every error in this Wiki article is web-exclusive.

=== Why do I sometimes get "504 Gateway Timeout" when running a report in web? ===

As outlined above, there are multiple web servers involved in the process of generating a PDF from a Crystal Report in the web, and each one of them has their own server-level timeouts. The web server connecting you to the application API (Chromium, Presage API, EE API) might time you out, and so might the web server connecting the application API to the Crystal Server.

==== Can we make the timeouts longer? ====

The short answer is "not really". Since the timeouts are at the web server level (i.e., nginx/Apache) all requests to that server have the same timeout. We could decide not to time any request out until several minutes have passed, but if a request is taking that long, it ''should'' time out.

=== How is Report Queue, the Python application, involved in this? ===

It's not. Crystal Server and Report Queue are completely separate applications. Crystal Server only generates PDF previews. Report Queue handles printing and emailing reports. Crystal Server is written in Node.js, Report Queue is written in Python. Their main similarity is that they both invoke Report Commander to generate the PDF file.

=== Why do Presage customers need set up manually? ===

Presage customers (generally) are on their own VM, and therefore database server. Therefore, they need their own entries in the Crystal Server config file.

Theoretically SMB customers, since they're on the same server, could share a config, but that hasn't been explored as of 2/4/2026.

=== Why do Enterprise customers need set up manually? ===

Enterprise customers are generally on their own VM or server. Additionally, EE customers might not want to use our central server, and might want to host their own. Therefore, they need their own entries in the Crystal Server config file, or their own Crystal Server instance entirely.

== Common Errors (Table Mode) ==

This table will hold the answers to (probably) any error you will encounter running reports in Presage Web

{| class="wikitable" style=""
|+ Common Errors
|-
! style="min-width: 100px;"| Error !! Description !! How to Fix
|-
| Invalid Session. Try logging out and logging back in. || This means that the report server was not able to verify your session. Either your session has expired, or the Crystal Server is not configured for that database. The most likely cause of this is, if logging out and back in doesn't fix it, is that the (generally Presage) customer hasn't been set up on the Crystal Server, or some configuration has changed. || If the config for that customer is missing, then add it matching the template. If it is present, make sure that the Crystal Server and Chromium/Presage API are configured with the same DB URL. Otherwise, check the ODBC connection and DB credentials. Charles can check the logs to double check the URLs are good, as well as update the config file. Brian can then restart the Crystal Server service to load the updated configuration.
|-
| rowspan="5" |Error running report. Double check the report parameters and try again. || This means that Report Commander did not receive the correct amount of parameters for the report. Often times, the report will run fine on desktop, because the Crystal SDK can "fill in the gaps" or ignore extra parameters, while the web Report Viewer cannot, and needs a row in reportparameter for every parameter. Check the <code>Report Viewer > History</code> tab for more error details || Generally, update the report and re-run adders, but '''See Below''' for more details, and check <code>Report Viewer > History</code> for more parameter and error details. If updating the report and adder doesn't fix it, it's possible that they are out of date and need fixed.
|-
| '''"Invalid value for <parameter>"''' means Report Commander received an invalid value for the listed parameter. Usually this just means you forgot to fill a parameter out, but could be caused by by an outdated report / adders. || Make sure all parameters are filled out.
|-
| '''"Parameter not found in report: <parameter>"''' means that a parameter was passed to the report that the report doesn't expect. || If caused by an out-of-date report (more common), update the report. If caused by out-of-date adders, re-run adders.
|-
| '''"Missing parameter values"''' means that the report was not passed all expected parameters. Normally, this is because a parameter was added to the report, and the adders are out of date. || Re-run adders.
|-
| '''"The types of the parameter field and parameter field current values are not compatible"''' means that Crystal was passed a parameter value of the wrong type for that parameter. For example, a string instead of a number || Make sure ITrack is sending parameters of the type the report expects to receive
|-
|| (I can't remember the error message) || Missing / invalid ODBC configuration. I think this presents as "could not connect to the database" or something to that effect. Sometimes it'll give you a "database vendor code" just like ITrack desktop. || Depending on the error code, Brian can make sure the ODBC connection is valid, and give Charles the name to check that the ODBC connection name in the Crystal Server config is correct. But some error codes like 1064 are unrelated to the odbc setup
|-
|| Invalid Report || The Crystal Server failed to find the report with the specified name/type. || Make sure the report exists in the customer database with the given name and type, and a valid <code>report.fileid</code>. In Presage, there used to be a bug where running reports with a non-English language selected would fail with this error.
|-
|| The file or directory is corrupted and unreadable || This would come up every so often because the D drive on Bunnahabhain was failing. It shouldn't happen anymore. || It shouldn't happen again, but if it does, delete the cached report file from <code>M:\report_cache</code> on Bunnahabhain. Maybe reupload the report if it persists after that.
|-
|| Database logon failed || ODBC could not connect to the database || Ask Brian (or maybe someone else from @Systems) to double check the ODBC connection on Bunnahabhain for that customer
|-
|| <code>Database Vendor Code (code)</code> || There was some MySQL error. Look up the error code. || Might depend on the error code, but it's probably because of a bad query in the report. Reupload report.
|-
|| <code>Internal Server Error</code> || You're probably on a version of EEW that doesn't forward the error to the client properly. || Check Report Viewer > History to see the actual error
|}

=== Other Errors ===

<code>Error: WARNING: MYSQL_OPT_RECONNECT is deprecated and will be removed in a future version.</code> - Disable "Auto Reconnect" on ODBC. Presents as "Unkown Error" or "Internal Server Error" in the UI

== Logs ==

The log file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\crystalserverservice.log</code>

A normal log entry for a report job looks like this:

<pre>
Connection created for 'hosteddb-southeast.isoftdata.com.373487'
args [
'-report="D:\\Node\\crystal-reports-server\\cache\\A95AC82D42C7A2A9AFF9F720DA5F3159.rpt"',
'-login!={server:reporting_hosted_southeast}{database:373487}',
'-exportfile="D:\\Node\\crystal-reports-server\\cache\\output\\default_invoice_2024-12-03T19-20-25.872Z.pdf"',
'-exportformat="PDF"',
'-namedparameters invoicenum="5150"'
]
Destroying connection for 'hosteddb-southeast.isoftdata.com.373487'
</pre>

If you see a message like this, then the Crystal Server (not ODBC) failed to connect to the database, and there will probably be a logged request body right below it. The logged request body should have the db host sent from the application, which can be compared to the valid hosts in the config file

<pre>
Destroying connection for 'iceriver.presageanalytics.com.UNKNOWN DATABASE'
</pre>

The most common errors you'll see start like this and will show the command used to run Report Commander as well as a more-detailed error message in a mess of JSON.

<pre>
ReportError: A Report Commander error has occurred
</pre>

== Configuration ==

This will go over how to configure a customer on the Crystal Server, not so much how to deploy and configure a new Crystal Server.

The config file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\config.json</code>

Generally, you just need to set the host, user, password, and odbc data sources for a new connection. However, host MUST be unique, and MUST match the ITrack/Presage server config, as that's what's used to look up the rest of the connection info. Most of the time you can just add another entry to the JSON, like so

<code><pre>{
"host": "HOST",
"user": "USER",
"password": "PASSWORD",
"odbcDataSource": "ODBC DATA SOURCE NAME"
}</pre></code>

In some cases you might also need to set the <code>caPath</code>, <code>certPath</code>, <code>keyPath</code> properties depending on the SSL config. See other configured hosts for examples.

After adding to the JSON, restart the <code>CrystalServer</code> service to apply any changes. See below for more product-specific details.

=== Chromium ===

Does not have to be configured per-customer. One config per VM. The users have more security and so they use more of the SSL options than other users

=== Presage Web/API ===

<code>REPORT_SERVER_URI</code> specifies the report server URI used by the server, and <code>MYSQL_HOST</code> specifies the DB host. <code>EXTERNAL_DB_HOST</code> will be sent to the Crystal Server instead of <code>MYSQL_HOST</code>, if specified. '''Either <code>MYSQL_HOST</code> or <code>EXTERNAL_DB_HOST</code> MUST match the <code>host</code> in the Crystal Server config file or it will not work!'''

==== SMB ====

Currently (12/04/2024), Culligan GI is the only Presage SMB customer, and was configured individually. Maybe in the future, Presage SMB will work like Chromium and just have one config per VM, but that's not currently the case.

Since the setup for SMB clients is slightly different, the <code>MYSQL_HOST</code> is an "internal" IP, but we need an external host that matches what the Crystal Server knows. To get around this, specify this ENV variable:<code>EXTERNAL_DB_HOST: <customername>-database.presageanalytics.com</code>. Make sure the URL matches the one in the Crystal Server config. Apparently, SMB DB URLs will always have <code>-database</code> in them since the SMB docker containers don't run on the same iron as MySQL.

As of 02/03/2025, there's also Bartlett, which had some issues setting it up related to SSL. Brian fixed it, I'm not sure what he did. I think they're also set up slightly differently than Culligan GI

==== Self-Hosted ====

If they're okay hitting our Crystal Server, we just need to make sure that their database can be reached on Bunnahabhain, then the setup is the same as a hosted yard.

If not, we'll have to deploy it to a Windows server they control, and set the <code>REPORT_SERVER_URI</code> ENV variable in the API to the proper URI. Presage API will have to be able to reach <code><The Server URL>/process_report</code> in order to generate the reports

=== Enterprise Web/API ===

If we host the customer, we should just set them up on our Crystal Server. Follow the general steps for configuring them in the Crystal Server config.json, then set some ENV variables in Portainer:

* <code>REPORT_SERVER_URI: http://print.itrackchromium.com</code>
* <code>EXTERNAL_DB_HOST: example-url.itrackenterprise.com</code>

WG, UT&W, & QBT are currently (07/08/25) the only EE customers with the web report viewer on, and they also had to have the caPath set in the crystal server config to the old/not-2024 ca cert. Not sure if that'll be true for other EE customers, but it was for them.

If they're self hosted, and don't want to use our Crystal Server, follow the steps under "Deployment", then set the above ENV variables to the proper values for their setup.

== Updating ==

Not 100% sure since it's been awhile, but I'm pretty sure the process is basically:
1. Build the Crystal Server to an exe again
2. Replace the old exe on BH
3. Restart CrystalServer service

== Deployment ==

For 99% of customers, this section will not apply. But in the event that a self-hosted customer wants to host their own Crystal Server, this is probably how.

* Locate a Windows Server
* Install Report Commander on it
* Run CrystalServerSetup.exe from dl.isoftdata.com, I think this sets up the service to make it run in the background and on startup?
* Get the latest EXE or build a new one from https://github.com/ISoft-Data-Systems/crystal-reports-server and replace the old EXE from the installer
* Restart the CrystalServer service
* Make sure the service is reachable from wherever the Presage API is running
* At this point, they should be able to make a request to <code>serveruri</code>/process_report and get a report back.

== Misc / Notes ==

Housby has Crystal Server deployed to generate invoice PDFs for an ecommerce integration. They're using a version before we compiled it to an exe, so if they ever run into bugs or need an update it will be a little different

Web Report Viewer Troubleshooting

2026-02-04T18:00:29Z

Ckaup: /* FAQ */

This article applies to Presage Web and ITrack Chromium. The web Report Viewer will give a general error, error details are logged to the reportqueue table and can be viewed in the "History" (web) or "Print Queue" (desktop) tab of the Report Viewer screen.

== Terms ==

* Crystal Server - the Node.JS application that uses Report Commander to generate the report PDF. Runs on Bunnahabhain. '''This application is not the same as Report Queue.'''
* Report Commander - command line application used to generate report PDFs by the Crystal Server (and Report Queue)
* Report Queue - python application that reads from reportqueue table to send emails and print to a printer. '''Report Queue is separate from Crystal Server, and the two systems do not interact.'''
* reportqueue - a table in the database that logs report runs.
* reportparameter - a table in the database that associates parameters to reports

== FAQ ==

=== How does the web report viewer work? ===

Since we can't run crystal reports directly in the browser, we need to run them on a central server and send them back to the web browser. There are multiple servers involved in this process, which I'll outline below

* The report and parameter list are loaded from the application's API (Chromium, Presage API, EE API)
* The user selects a report, fills out parameters, and clicks "Preview"
* A request is sent to the application backend (Chromium, Presage API, EE API)
* Application backend sends a request to Crystal Server, running on Bunnahabhain, or a customer server if relevant. This requests includes details of the report to run, which database to run it on, and a valid session token for that database.
* Bunnahabhain takes this request, and attempts to validate the given session token in the given database. If this fails, such as if the token is invalid or it can't connect to the database, an "Invalid Session" error is thrown.
* After the session is validated, Crystal Server will download the report file from the customer's database, and run default parameter queries. The report is saved to the "cache directory" specified in the config, with the file's hash as the file name.
* Then, Crystal Server creates a command line string to run Report Commander for the given report and parameters
* Report Commander is then invoked to generate the PDF, which is saved to a folder in the Crystal Server's "cache directory". If Report Commander throws an error, it is forwarded to the application API (Chromium, Presage API, EE API), which saves it to the <code>reportqueue</code> table and forwards that error to the client, where it is displayed.
* If it succeeds, the report file is base64 encoded and sent back to the application API (Chromium, Presage API, EE API), along with the time it took to execute the report.
* The application API receives the request, saves the details to <code>reportqueue</code>/<code>reportqueueparameter</code>, and returns the base64 encoded PDF to the client
* The client receives the response from its backend, and displays the base64 encoded PDF in the browser using an <code><object/></code> tag

==== How is that different from desktop? ====

ITrack desktop talks directly to the Crystal Reports SDK on the individual workstation, instead of sending report jobs to a central server (Bunnahabhain) running Crystal Server.

=== Why can't web work the same way as desktop? ===

Chromium, Presage Web, and Enterprise Web run inside of a web browser, and can therefore be used on multiple operating systems without installing anything. Crystal Reports SDK is Windows-only and requires installation. Therefore, we need a central server to generate the pdf and send it back to the web browser (with some extra steps in between)

=== Why does this report run on desktop, but not on web? ===

As outlined above, web and desktop have entirely different stacks for running crystal reports. In short, web uses Report Commander instead of the Crystal SDK. I don't know exactly how the official Crystal SDK works, but it seems to be more tolerant to being passed extra parameters, or missing parameters. Report Commander is pickier so it will throw when you give it an extra parameter not found in the report, or if you are missing a required parameter value. As a result, basically every error in this Wiki article is web-exclusive.

=== Why do I sometimes get "504 Gateway Timeout" when running a report in web? ===

As outlined above, there are multiple web servers involved in the process of generating a PDF from a Crystal Report in the web, and each one of them has their own server-level timeouts. The web server connecting you to the application API (Chromium, Presage API, EE API) might time you out, and so might the web server connecting the application API to the Crystal Server.

==== Can we make the timeouts longer? ====

The short answer is "not really". Since the timeouts are at the web server level (i.e., nginx/Apache) all requests to that server have the same timeout. We could decide not to time any request out until several minutes have passed, but if a request is taking that long, it ''should'' time out.

=== Why do Presage customers need set up manually? ===

Presage customers (generally) are on their own VM, and therefore database server. Therefore, they need their own entries in the Crystal Server config file.

Theoretically SMB customers, since they're on the same server, could share a config, but that hasn't been explored as of 2/4/2026.

=== Why do Enterprise customers need set up manually? ===

Enterprise customers are generally on their own VM or server. Additionally, EE customers might not want to use our central server, and might want to host their own. Therefore, they need their own entries in the Crystal Server config file, or their own Crystal Server instance entirely.

== Common Errors (Table Mode) ==

This table will hold the answers to (probably) any error you will encounter running reports in Presage Web

{| class="wikitable" style=""
|+ Common Errors
|-
! style="min-width: 100px;"| Error !! Description !! How to Fix
|-
| Invalid Session. Try logging out and logging back in. || This means that the report server was not able to verify your session. Either your session has expired, or the Crystal Server is not configured for that database. The most likely cause of this is, if logging out and back in doesn't fix it, is that the (generally Presage) customer hasn't been set up on the Crystal Server, or some configuration has changed. || If the config for that customer is missing, then add it matching the template. If it is present, make sure that the Crystal Server and Chromium/Presage API are configured with the same DB URL. Otherwise, check the ODBC connection and DB credentials. Charles can check the logs to double check the URLs are good, as well as update the config file. Brian can then restart the Crystal Server service to load the updated configuration.
|-
| rowspan="5" |Error running report. Double check the report parameters and try again. || This means that Report Commander did not receive the correct amount of parameters for the report. Often times, the report will run fine on desktop, because the Crystal SDK can "fill in the gaps" or ignore extra parameters, while the web Report Viewer cannot, and needs a row in reportparameter for every parameter. Check the <code>Report Viewer > History</code> tab for more error details || Generally, update the report and re-run adders, but '''See Below''' for more details, and check <code>Report Viewer > History</code> for more parameter and error details. If updating the report and adder doesn't fix it, it's possible that they are out of date and need fixed.
|-
| '''"Invalid value for <parameter>"''' means Report Commander received an invalid value for the listed parameter. Usually this just means you forgot to fill a parameter out, but could be caused by by an outdated report / adders. || Make sure all parameters are filled out.
|-
| '''"Parameter not found in report: <parameter>"''' means that a parameter was passed to the report that the report doesn't expect. || If caused by an out-of-date report (more common), update the report. If caused by out-of-date adders, re-run adders.
|-
| '''"Missing parameter values"''' means that the report was not passed all expected parameters. Normally, this is because a parameter was added to the report, and the adders are out of date. || Re-run adders.
|-
| '''"The types of the parameter field and parameter field current values are not compatible"''' means that Crystal was passed a parameter value of the wrong type for that parameter. For example, a string instead of a number || Make sure ITrack is sending parameters of the type the report expects to receive
|-
|| (I can't remember the error message) || Missing / invalid ODBC configuration. I think this presents as "could not connect to the database" or something to that effect. Sometimes it'll give you a "database vendor code" just like ITrack desktop. || Depending on the error code, Brian can make sure the ODBC connection is valid, and give Charles the name to check that the ODBC connection name in the Crystal Server config is correct. But some error codes like 1064 are unrelated to the odbc setup
|-
|| Invalid Report || The Crystal Server failed to find the report with the specified name/type. || Make sure the report exists in the customer database with the given name and type, and a valid <code>report.fileid</code>. In Presage, there used to be a bug where running reports with a non-English language selected would fail with this error.
|-
|| The file or directory is corrupted and unreadable || This would come up every so often because the D drive on Bunnahabhain was failing. It shouldn't happen anymore. || It shouldn't happen again, but if it does, delete the cached report file from <code>M:\report_cache</code> on Bunnahabhain. Maybe reupload the report if it persists after that.
|-
|| Database logon failed || ODBC could not connect to the database || Ask Brian (or maybe someone else from @Systems) to double check the ODBC connection on Bunnahabhain for that customer
|-
|| <code>Database Vendor Code (code)</code> || There was some MySQL error. Look up the error code. || Might depend on the error code, but it's probably because of a bad query in the report. Reupload report.
|-
|| <code>Internal Server Error</code> || You're probably on a version of EEW that doesn't forward the error to the client properly. || Check Report Viewer > History to see the actual error
|}

=== Other Errors ===

<code>Error: WARNING: MYSQL_OPT_RECONNECT is deprecated and will be removed in a future version.</code> - Disable "Auto Reconnect" on ODBC. Presents as "Unkown Error" or "Internal Server Error" in the UI

== Logs ==

The log file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\crystalserverservice.log</code>

A normal log entry for a report job looks like this:

<pre>
Connection created for 'hosteddb-southeast.isoftdata.com.373487'
args [
'-report="D:\\Node\\crystal-reports-server\\cache\\A95AC82D42C7A2A9AFF9F720DA5F3159.rpt"',
'-login!={server:reporting_hosted_southeast}{database:373487}',
'-exportfile="D:\\Node\\crystal-reports-server\\cache\\output\\default_invoice_2024-12-03T19-20-25.872Z.pdf"',
'-exportformat="PDF"',
'-namedparameters invoicenum="5150"'
]
Destroying connection for 'hosteddb-southeast.isoftdata.com.373487'
</pre>

If you see a message like this, then the Crystal Server (not ODBC) failed to connect to the database, and there will probably be a logged request body right below it. The logged request body should have the db host sent from the application, which can be compared to the valid hosts in the config file

<pre>
Destroying connection for 'iceriver.presageanalytics.com.UNKNOWN DATABASE'
</pre>

The most common errors you'll see start like this and will show the command used to run Report Commander as well as a more-detailed error message in a mess of JSON.

<pre>
ReportError: A Report Commander error has occurred
</pre>

== Configuration ==

This will go over how to configure a customer on the Crystal Server, not so much how to deploy and configure a new Crystal Server.

The config file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\config.json</code>

Generally, you just need to set the host, user, password, and odbc data sources for a new connection. However, host MUST be unique, and MUST match the ITrack/Presage server config, as that's what's used to look up the rest of the connection info. Most of the time you can just add another entry to the JSON, like so

<code><pre>{
"host": "HOST",
"user": "USER",
"password": "PASSWORD",
"odbcDataSource": "ODBC DATA SOURCE NAME"
}</pre></code>

In some cases you might also need to set the <code>caPath</code>, <code>certPath</code>, <code>keyPath</code> properties depending on the SSL config. See other configured hosts for examples.

After adding to the JSON, restart the <code>CrystalServer</code> service to apply any changes. See below for more product-specific details.

=== Chromium ===

Does not have to be configured per-customer. One config per VM. The users have more security and so they use more of the SSL options than other users

=== Presage Web/API ===

<code>REPORT_SERVER_URI</code> specifies the report server URI used by the server, and <code>MYSQL_HOST</code> specifies the DB host. <code>EXTERNAL_DB_HOST</code> will be sent to the Crystal Server instead of <code>MYSQL_HOST</code>, if specified. '''Either <code>MYSQL_HOST</code> or <code>EXTERNAL_DB_HOST</code> MUST match the <code>host</code> in the Crystal Server config file or it will not work!'''

==== SMB ====

Currently (12/04/2024), Culligan GI is the only Presage SMB customer, and was configured individually. Maybe in the future, Presage SMB will work like Chromium and just have one config per VM, but that's not currently the case.

Since the setup for SMB clients is slightly different, the <code>MYSQL_HOST</code> is an "internal" IP, but we need an external host that matches what the Crystal Server knows. To get around this, specify this ENV variable:<code>EXTERNAL_DB_HOST: <customername>-database.presageanalytics.com</code>. Make sure the URL matches the one in the Crystal Server config. Apparently, SMB DB URLs will always have <code>-database</code> in them since the SMB docker containers don't run on the same iron as MySQL.

As of 02/03/2025, there's also Bartlett, which had some issues setting it up related to SSL. Brian fixed it, I'm not sure what he did. I think they're also set up slightly differently than Culligan GI

==== Self-Hosted ====

If they're okay hitting our Crystal Server, we just need to make sure that their database can be reached on Bunnahabhain, then the setup is the same as a hosted yard.

If not, we'll have to deploy it to a Windows server they control, and set the <code>REPORT_SERVER_URI</code> ENV variable in the API to the proper URI. Presage API will have to be able to reach <code><The Server URL>/process_report</code> in order to generate the reports

=== Enterprise Web/API ===

If we host the customer, we should just set them up on our Crystal Server. Follow the general steps for configuring them in the Crystal Server config.json, then set some ENV variables in Portainer:

* <code>REPORT_SERVER_URI: http://print.itrackchromium.com</code>
* <code>EXTERNAL_DB_HOST: example-url.itrackenterprise.com</code>

WG, UT&W, & QBT are currently (07/08/25) the only EE customers with the web report viewer on, and they also had to have the caPath set in the crystal server config to the old/not-2024 ca cert. Not sure if that'll be true for other EE customers, but it was for them.

If they're self hosted, and don't want to use our Crystal Server, follow the steps under "Deployment", then set the above ENV variables to the proper values for their setup.

== Updating ==

Not 100% sure since it's been awhile, but I'm pretty sure the process is basically:
1. Build the Crystal Server to an exe again
2. Replace the old exe on BH
3. Restart CrystalServer service

== Deployment ==

For 99% of customers, this section will not apply. But in the event that a self-hosted customer wants to host their own Crystal Server, this is probably how.

* Locate a Windows Server
* Install Report Commander on it
* Run CrystalServerSetup.exe from dl.isoftdata.com, I think this sets up the service to make it run in the background and on startup?
* Get the latest EXE or build a new one from https://github.com/ISoft-Data-Systems/crystal-reports-server and replace the old EXE from the installer
* Restart the CrystalServer service
* Make sure the service is reachable from wherever the Presage API is running
* At this point, they should be able to make a request to <code>serveruri</code>/process_report and get a report back.

== Misc / Notes ==

Housby has Crystal Server deployed to generate invoice PDFs for an ecommerce integration. They're using a version before we compiled it to an exe, so if they ever run into bugs or need an update it will be a little different

Web Report Viewer Troubleshooting

2026-02-04T17:52:22Z

Ckaup: /* Why does this report run on desktop, but not on web? */

This article applies to Presage Web and ITrack Chromium. The web Report Viewer will give a general error, error details are logged to the reportqueue table and can be viewed in the "History" (web) or "Print Queue" (desktop) tab of the Report Viewer screen.

== Terms ==

* Crystal Server - the Node.JS application that uses Report Commander to generate the report PDF. Runs on Bunnahabhain. '''This application is not the same as Report Queue.'''
* Report Commander - command line application used to generate report PDFs by the Crystal Server (and Report Queue)
* Report Queue - python application that reads from reportqueue table to send emails and print to a printer. '''Report Queue is separate from Crystal Server, and the two systems do not interact.'''
* reportqueue - a table in the database that logs report runs.
* reportparameter - a table in the database that associates parameters to reports

== FAQ ==

=== How does the web report viewer work? ===

Since we can't run crystal reports directly in the browser, we need to run them on a central server and send them back to the web browser. There are multiple servers involved in this process, which I'll outline below

* The report and parameter list are loaded from the application's API (Chromium, Presage API, EE API)
* The user selects a report, fills out parameters, and clicks "Preview"
* A request is sent to the application backend (Chromium, Presage API, EE API)
* Application backend sends a request to Crystal Server, running on Bunnahabhain, or a customer server if relevant. This requests includes details of the report to run, which database to run it on, and a valid session token for that database.
* Bunnahabhain takes this request, and attempts to validate the given session token in the given database. If this fails, such as if the token is invalid or it can't connect to the database, an "Invalid Session" error is thrown.
* After the session is validated, Crystal Server will download the report file from the customer's database, and run default parameter queries. The report is saved to the "cache directory" specified in the config, with the file's hash as the file name.
* Then, Crystal Server creates a command line string to run Report Commander for the given report and parameters
* Report Commander is then invoked to generate the PDF, which is saved to a folder in the Crystal Server's "cache directory". If Report Commander throws an error, it is forwarded to the application API (Chromium, Presage API, EE API), which saves it to the <code>reportqueue</code> table and forwards that error to the client, where it is displayed.
* If it succeeds, the report file is base64 encoded and sent back to the application API (Chromium, Presage API, EE API), along with the time it took to execute the report.
* The application API receives the request, saves the details to <code>reportqueue</code>/<code>reportqueueparameter</code>, and returns the base64 encoded PDF to the client
* The client receives the response from its backend, and displays the base64 encoded PDF in the browser using an <code><object/></code> tag

=== How is that different from desktop? ===

ITrack desktop talks directly to the Crystal Reports SDK on the individual workstation, instead of sending report jobs to a central server (Bunnahabhain) running Crystal Server.

=== Why can't web work the same way as desktop? ===

Chromium, Presage Web, and Enterprise Web run inside of a web browser, and can therefore be used on multiple operating systems without installing anything. Crystal Reports SDK is Windows-only and requires installation. Therefore, we need a central server to generate the pdf and send it back to the web browser (with some extra steps in between)

=== Why does this report run on desktop, but not on web? ===

As outlined above, web and desktop have entirely different stacks for running crystal reports. In short, web uses Report Commander instead of the Crystal SDK. I don't know exactly how the official Crystal SDK works, but it seems to be more tolerant to being passed extra parameters, or missing parameters. Report Commander is pickier so it will throw when you give it an extra parameter not found in the report, or if you are missing a required parameter value. As a result, basically every error in this Wiki article is web-exclusive.

=== Why do Presage customers need set up manually? ===

Presage customers (generally) are on their own VM, and therefore database server. Therefore, they need their own entries in the Crystal Server config file.

Theoretically SMB customers, since they're on the same server, could share a config, but that hasn't been explored as of 2/4/2026.

=== Why do Enterprise customers need set up manually? ===

Enterprise customers are generally on their own VM or server. Additionally, EE customers might not want to use our central server, and might want to host their own. Therefore, they need their own entries in the Crystal Server config file, or their own Crystal Server instance entirely.

== Common Errors (Table Mode) ==

This table will hold the answers to (probably) any error you will encounter running reports in Presage Web

{| class="wikitable" style=""
|+ Common Errors
|-
! style="min-width: 100px;"| Error !! Description !! How to Fix
|-
| Invalid Session. Try logging out and logging back in. || This means that the report server was not able to verify your session. Either your session has expired, or the Crystal Server is not configured for that database. The most likely cause of this is, if logging out and back in doesn't fix it, is that the (generally Presage) customer hasn't been set up on the Crystal Server, or some configuration has changed. || If the config for that customer is missing, then add it matching the template. If it is present, make sure that the Crystal Server and Chromium/Presage API are configured with the same DB URL. Otherwise, check the ODBC connection and DB credentials. Charles can check the logs to double check the URLs are good, as well as update the config file. Brian can then restart the Crystal Server service to load the updated configuration.
|-
| rowspan="5" |Error running report. Double check the report parameters and try again. || This means that Report Commander did not receive the correct amount of parameters for the report. Often times, the report will run fine on desktop, because the Crystal SDK can "fill in the gaps" or ignore extra parameters, while the web Report Viewer cannot, and needs a row in reportparameter for every parameter. Check the <code>Report Viewer > History</code> tab for more error details || Generally, update the report and re-run adders, but '''See Below''' for more details, and check <code>Report Viewer > History</code> for more parameter and error details. If updating the report and adder doesn't fix it, it's possible that they are out of date and need fixed.
|-
| '''"Invalid value for <parameter>"''' means Report Commander received an invalid value for the listed parameter. Usually this just means you forgot to fill a parameter out, but could be caused by by an outdated report / adders. || Make sure all parameters are filled out.
|-
| '''"Parameter not found in report: <parameter>"''' means that a parameter was passed to the report that the report doesn't expect. || If caused by an out-of-date report (more common), update the report. If caused by out-of-date adders, re-run adders.
|-
| '''"Missing parameter values"''' means that the report was not passed all expected parameters. Normally, this is because a parameter was added to the report, and the adders are out of date. || Re-run adders.
|-
| '''"The types of the parameter field and parameter field current values are not compatible"''' means that Crystal was passed a parameter value of the wrong type for that parameter. For example, a string instead of a number || Make sure ITrack is sending parameters of the type the report expects to receive
|-
|| (I can't remember the error message) || Missing / invalid ODBC configuration. I think this presents as "could not connect to the database" or something to that effect. Sometimes it'll give you a "database vendor code" just like ITrack desktop. || Depending on the error code, Brian can make sure the ODBC connection is valid, and give Charles the name to check that the ODBC connection name in the Crystal Server config is correct. But some error codes like 1064 are unrelated to the odbc setup
|-
|| Invalid Report || The Crystal Server failed to find the report with the specified name/type. || Make sure the report exists in the customer database with the given name and type, and a valid <code>report.fileid</code>. In Presage, there used to be a bug where running reports with a non-English language selected would fail with this error.
|-
|| The file or directory is corrupted and unreadable || This would come up every so often because the D drive on Bunnahabhain was failing. It shouldn't happen anymore. || It shouldn't happen again, but if it does, delete the cached report file from <code>M:\report_cache</code> on Bunnahabhain. Maybe reupload the report if it persists after that.
|-
|| Database logon failed || ODBC could not connect to the database || Ask Brian (or maybe someone else from @Systems) to double check the ODBC connection on Bunnahabhain for that customer
|-
|| <code>Database Vendor Code (code)</code> || There was some MySQL error. Look up the error code. || Might depend on the error code, but it's probably because of a bad query in the report. Reupload report.
|-
|| <code>Internal Server Error</code> || You're probably on a version of EEW that doesn't forward the error to the client properly. || Check Report Viewer > History to see the actual error
|}

=== Other Errors ===

<code>Error: WARNING: MYSQL_OPT_RECONNECT is deprecated and will be removed in a future version.</code> - Disable "Auto Reconnect" on ODBC. Presents as "Unkown Error" or "Internal Server Error" in the UI

== Logs ==

The log file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\crystalserverservice.log</code>

A normal log entry for a report job looks like this:

<pre>
Connection created for 'hosteddb-southeast.isoftdata.com.373487'
args [
'-report="D:\\Node\\crystal-reports-server\\cache\\A95AC82D42C7A2A9AFF9F720DA5F3159.rpt"',
'-login!={server:reporting_hosted_southeast}{database:373487}',
'-exportfile="D:\\Node\\crystal-reports-server\\cache\\output\\default_invoice_2024-12-03T19-20-25.872Z.pdf"',
'-exportformat="PDF"',
'-namedparameters invoicenum="5150"'
]
Destroying connection for 'hosteddb-southeast.isoftdata.com.373487'
</pre>

If you see a message like this, then the Crystal Server (not ODBC) failed to connect to the database, and there will probably be a logged request body right below it. The logged request body should have the db host sent from the application, which can be compared to the valid hosts in the config file

<pre>
Destroying connection for 'iceriver.presageanalytics.com.UNKNOWN DATABASE'
</pre>

The most common errors you'll see start like this and will show the command used to run Report Commander as well as a more-detailed error message in a mess of JSON.

<pre>
ReportError: A Report Commander error has occurred
</pre>

== Configuration ==

This will go over how to configure a customer on the Crystal Server, not so much how to deploy and configure a new Crystal Server.

The config file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\config.json</code>

Generally, you just need to set the host, user, password, and odbc data sources for a new connection. However, host MUST be unique, and MUST match the ITrack/Presage server config, as that's what's used to look up the rest of the connection info. Most of the time you can just add another entry to the JSON, like so

<code><pre>{
"host": "HOST",
"user": "USER",
"password": "PASSWORD",
"odbcDataSource": "ODBC DATA SOURCE NAME"
}</pre></code>

In some cases you might also need to set the <code>caPath</code>, <code>certPath</code>, <code>keyPath</code> properties depending on the SSL config. See other configured hosts for examples.

After adding to the JSON, restart the <code>CrystalServer</code> service to apply any changes. See below for more product-specific details.

=== Chromium ===

Does not have to be configured per-customer. One config per VM. The users have more security and so they use more of the SSL options than other users

=== Presage Web/API ===

<code>REPORT_SERVER_URI</code> specifies the report server URI used by the server, and <code>MYSQL_HOST</code> specifies the DB host. <code>EXTERNAL_DB_HOST</code> will be sent to the Crystal Server instead of <code>MYSQL_HOST</code>, if specified. '''Either <code>MYSQL_HOST</code> or <code>EXTERNAL_DB_HOST</code> MUST match the <code>host</code> in the Crystal Server config file or it will not work!'''

==== SMB ====

Currently (12/04/2024), Culligan GI is the only Presage SMB customer, and was configured individually. Maybe in the future, Presage SMB will work like Chromium and just have one config per VM, but that's not currently the case.

Since the setup for SMB clients is slightly different, the <code>MYSQL_HOST</code> is an "internal" IP, but we need an external host that matches what the Crystal Server knows. To get around this, specify this ENV variable:<code>EXTERNAL_DB_HOST: <customername>-database.presageanalytics.com</code>. Make sure the URL matches the one in the Crystal Server config. Apparently, SMB DB URLs will always have <code>-database</code> in them since the SMB docker containers don't run on the same iron as MySQL.

As of 02/03/2025, there's also Bartlett, which had some issues setting it up related to SSL. Brian fixed it, I'm not sure what he did. I think they're also set up slightly differently than Culligan GI

==== Self-Hosted ====

If they're okay hitting our Crystal Server, we just need to make sure that their database can be reached on Bunnahabhain, then the setup is the same as a hosted yard.

If not, we'll have to deploy it to a Windows server they control, and set the <code>REPORT_SERVER_URI</code> ENV variable in the API to the proper URI. Presage API will have to be able to reach <code><The Server URL>/process_report</code> in order to generate the reports

=== Enterprise Web/API ===

If we host the customer, we should just set them up on our Crystal Server. Follow the general steps for configuring them in the Crystal Server config.json, then set some ENV variables in Portainer:

* <code>REPORT_SERVER_URI: http://print.itrackchromium.com</code>
* <code>EXTERNAL_DB_HOST: example-url.itrackenterprise.com</code>

WG, UT&W, & QBT are currently (07/08/25) the only EE customers with the web report viewer on, and they also had to have the caPath set in the crystal server config to the old/not-2024 ca cert. Not sure if that'll be true for other EE customers, but it was for them.

If they're self hosted, and don't want to use our Crystal Server, follow the steps under "Deployment", then set the above ENV variables to the proper values for their setup.

== Updating ==

Not 100% sure since it's been awhile, but I'm pretty sure the process is basically:
1. Build the Crystal Server to an exe again
2. Replace the old exe on BH
3. Restart CrystalServer service

== Deployment ==

For 99% of customers, this section will not apply. But in the event that a self-hosted customer wants to host their own Crystal Server, this is probably how.

* Locate a Windows Server
* Install Report Commander on it
* Run CrystalServerSetup.exe from dl.isoftdata.com, I think this sets up the service to make it run in the background and on startup?
* Get the latest EXE or build a new one from https://github.com/ISoft-Data-Systems/crystal-reports-server and replace the old EXE from the installer
* Restart the CrystalServer service
* Make sure the service is reachable from wherever the Presage API is running
* At this point, they should be able to make a request to <code>serveruri</code>/process_report and get a report back.

== Misc / Notes ==

Housby has Crystal Server deployed to generate invoice PDFs for an ecommerce integration. They're using a version before we compiled it to an exe, so if they ever run into bugs or need an update it will be a little different

Web Report Viewer Troubleshooting

2026-02-04T17:50:15Z

Ckaup:

This article applies to Presage Web and ITrack Chromium. The web Report Viewer will give a general error, error details are logged to the reportqueue table and can be viewed in the "History" (web) or "Print Queue" (desktop) tab of the Report Viewer screen.

== Terms ==

* Crystal Server - the Node.JS application that uses Report Commander to generate the report PDF. Runs on Bunnahabhain. '''This application is not the same as Report Queue.'''
* Report Commander - command line application used to generate report PDFs by the Crystal Server (and Report Queue)
* Report Queue - python application that reads from reportqueue table to send emails and print to a printer. '''Report Queue is separate from Crystal Server, and the two systems do not interact.'''
* reportqueue - a table in the database that logs report runs.
* reportparameter - a table in the database that associates parameters to reports

== FAQ ==

=== How does the web report viewer work? ===

Since we can't run crystal reports directly in the browser, we need to run them on a central server and send them back to the web browser. There are multiple servers involved in this process, which I'll outline below

* The report and parameter list are loaded from the application's API (Chromium, Presage API, EE API)
* The user selects a report, fills out parameters, and clicks "Preview"
* A request is sent to the application backend (Chromium, Presage API, EE API)
* Application backend sends a request to Crystal Server, running on Bunnahabhain, or a customer server if relevant. This requests includes details of the report to run, which database to run it on, and a valid session token for that database.
* Bunnahabhain takes this request, and attempts to validate the given session token in the given database. If this fails, such as if the token is invalid or it can't connect to the database, an "Invalid Session" error is thrown.
* After the session is validated, Crystal Server will download the report file from the customer's database, and run default parameter queries. The report is saved to the "cache directory" specified in the config, with the file's hash as the file name.
* Then, Crystal Server creates a command line string to run Report Commander for the given report and parameters
* Report Commander is then invoked to generate the PDF, which is saved to a folder in the Crystal Server's "cache directory". If Report Commander throws an error, it is forwarded to the application API (Chromium, Presage API, EE API), which saves it to the <code>reportqueue</code> table and forwards that error to the client, where it is displayed.
* If it succeeds, the report file is base64 encoded and sent back to the application API (Chromium, Presage API, EE API), along with the time it took to execute the report.
* The application API receives the request, saves the details to <code>reportqueue</code>/<code>reportqueueparameter</code>, and returns the base64 encoded PDF to the client
* The client receives the response from its backend, and displays the base64 encoded PDF in the browser using an <code><object/></code> tag

=== How is that different from desktop? ===

ITrack desktop talks directly to the Crystal Reports SDK on the individual workstation, instead of sending report jobs to a central server (Bunnahabhain) running Crystal Server.

=== Why can't web work the same way as desktop? ===

Chromium, Presage Web, and Enterprise Web run inside of a web browser, and can therefore be used on multiple operating systems without installing anything. Crystal Reports SDK is Windows-only and requires installation. Therefore, we need a central server to generate the pdf and send it back to the web browser (with some extra steps in between)

=== Why does this report run on desktop, but not on web? ===

As outlined above, web and desktop have entirely different stacks for running crystal reports. In short, web uses Report Commander instead of the Crystal SDK. I don't know exactly how the official Crystal SDK works,

=== Why do Presage customers need set up manually? ===

Presage customers (generally) are on their own VM, and therefore database server. Therefore, they need their own entries in the Crystal Server config file.

Theoretically SMB customers, since they're on the same server, could share a config, but that hasn't been explored as of 2/4/2026.

=== Why do Enterprise customers need set up manually? ===

Enterprise customers are generally on their own VM or server. Additionally, EE customers might not want to use our central server, and might want to host their own. Therefore, they need their own entries in the Crystal Server config file, or their own Crystal Server instance entirely.

== Common Errors (Table Mode) ==

This table will hold the answers to (probably) any error you will encounter running reports in Presage Web

{| class="wikitable" style=""
|+ Common Errors
|-
! style="min-width: 100px;"| Error !! Description !! How to Fix
|-
| Invalid Session. Try logging out and logging back in. || This means that the report server was not able to verify your session. Either your session has expired, or the Crystal Server is not configured for that database. The most likely cause of this is, if logging out and back in doesn't fix it, is that the (generally Presage) customer hasn't been set up on the Crystal Server, or some configuration has changed. || If the config for that customer is missing, then add it matching the template. If it is present, make sure that the Crystal Server and Chromium/Presage API are configured with the same DB URL. Otherwise, check the ODBC connection and DB credentials. Charles can check the logs to double check the URLs are good, as well as update the config file. Brian can then restart the Crystal Server service to load the updated configuration.
|-
| rowspan="5" |Error running report. Double check the report parameters and try again. || This means that Report Commander did not receive the correct amount of parameters for the report. Often times, the report will run fine on desktop, because the Crystal SDK can "fill in the gaps" or ignore extra parameters, while the web Report Viewer cannot, and needs a row in reportparameter for every parameter. Check the <code>Report Viewer > History</code> tab for more error details || Generally, update the report and re-run adders, but '''See Below''' for more details, and check <code>Report Viewer > History</code> for more parameter and error details. If updating the report and adder doesn't fix it, it's possible that they are out of date and need fixed.
|-
| '''"Invalid value for <parameter>"''' means Report Commander received an invalid value for the listed parameter. Usually this just means you forgot to fill a parameter out, but could be caused by by an outdated report / adders. || Make sure all parameters are filled out.
|-
| '''"Parameter not found in report: <parameter>"''' means that a parameter was passed to the report that the report doesn't expect. || If caused by an out-of-date report (more common), update the report. If caused by out-of-date adders, re-run adders.
|-
| '''"Missing parameter values"''' means that the report was not passed all expected parameters. Normally, this is because a parameter was added to the report, and the adders are out of date. || Re-run adders.
|-
| '''"The types of the parameter field and parameter field current values are not compatible"''' means that Crystal was passed a parameter value of the wrong type for that parameter. For example, a string instead of a number || Make sure ITrack is sending parameters of the type the report expects to receive
|-
|| (I can't remember the error message) || Missing / invalid ODBC configuration. I think this presents as "could not connect to the database" or something to that effect. Sometimes it'll give you a "database vendor code" just like ITrack desktop. || Depending on the error code, Brian can make sure the ODBC connection is valid, and give Charles the name to check that the ODBC connection name in the Crystal Server config is correct. But some error codes like 1064 are unrelated to the odbc setup
|-
|| Invalid Report || The Crystal Server failed to find the report with the specified name/type. || Make sure the report exists in the customer database with the given name and type, and a valid <code>report.fileid</code>. In Presage, there used to be a bug where running reports with a non-English language selected would fail with this error.
|-
|| The file or directory is corrupted and unreadable || This would come up every so often because the D drive on Bunnahabhain was failing. It shouldn't happen anymore. || It shouldn't happen again, but if it does, delete the cached report file from <code>M:\report_cache</code> on Bunnahabhain. Maybe reupload the report if it persists after that.
|-
|| Database logon failed || ODBC could not connect to the database || Ask Brian (or maybe someone else from @Systems) to double check the ODBC connection on Bunnahabhain for that customer
|-
|| <code>Database Vendor Code (code)</code> || There was some MySQL error. Look up the error code. || Might depend on the error code, but it's probably because of a bad query in the report. Reupload report.
|-
|| <code>Internal Server Error</code> || You're probably on a version of EEW that doesn't forward the error to the client properly. || Check Report Viewer > History to see the actual error
|}

=== Other Errors ===

<code>Error: WARNING: MYSQL_OPT_RECONNECT is deprecated and will be removed in a future version.</code> - Disable "Auto Reconnect" on ODBC. Presents as "Unkown Error" or "Internal Server Error" in the UI

== Logs ==

The log file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\crystalserverservice.log</code>

A normal log entry for a report job looks like this:

<pre>
Connection created for 'hosteddb-southeast.isoftdata.com.373487'
args [
'-report="D:\\Node\\crystal-reports-server\\cache\\A95AC82D42C7A2A9AFF9F720DA5F3159.rpt"',
'-login!={server:reporting_hosted_southeast}{database:373487}',
'-exportfile="D:\\Node\\crystal-reports-server\\cache\\output\\default_invoice_2024-12-03T19-20-25.872Z.pdf"',
'-exportformat="PDF"',
'-namedparameters invoicenum="5150"'
]
Destroying connection for 'hosteddb-southeast.isoftdata.com.373487'
</pre>

If you see a message like this, then the Crystal Server (not ODBC) failed to connect to the database, and there will probably be a logged request body right below it. The logged request body should have the db host sent from the application, which can be compared to the valid hosts in the config file

<pre>
Destroying connection for 'iceriver.presageanalytics.com.UNKNOWN DATABASE'
</pre>

The most common errors you'll see start like this and will show the command used to run Report Commander as well as a more-detailed error message in a mess of JSON.

<pre>
ReportError: A Report Commander error has occurred
</pre>

== Configuration ==

This will go over how to configure a customer on the Crystal Server, not so much how to deploy and configure a new Crystal Server.

The config file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\config.json</code>

Generally, you just need to set the host, user, password, and odbc data sources for a new connection. However, host MUST be unique, and MUST match the ITrack/Presage server config, as that's what's used to look up the rest of the connection info. Most of the time you can just add another entry to the JSON, like so

<code><pre>{
"host": "HOST",
"user": "USER",
"password": "PASSWORD",
"odbcDataSource": "ODBC DATA SOURCE NAME"
}</pre></code>

In some cases you might also need to set the <code>caPath</code>, <code>certPath</code>, <code>keyPath</code> properties depending on the SSL config. See other configured hosts for examples.

After adding to the JSON, restart the <code>CrystalServer</code> service to apply any changes. See below for more product-specific details.

=== Chromium ===

Does not have to be configured per-customer. One config per VM. The users have more security and so they use more of the SSL options than other users

=== Presage Web/API ===

<code>REPORT_SERVER_URI</code> specifies the report server URI used by the server, and <code>MYSQL_HOST</code> specifies the DB host. <code>EXTERNAL_DB_HOST</code> will be sent to the Crystal Server instead of <code>MYSQL_HOST</code>, if specified. '''Either <code>MYSQL_HOST</code> or <code>EXTERNAL_DB_HOST</code> MUST match the <code>host</code> in the Crystal Server config file or it will not work!'''

==== SMB ====

Currently (12/04/2024), Culligan GI is the only Presage SMB customer, and was configured individually. Maybe in the future, Presage SMB will work like Chromium and just have one config per VM, but that's not currently the case.

Since the setup for SMB clients is slightly different, the <code>MYSQL_HOST</code> is an "internal" IP, but we need an external host that matches what the Crystal Server knows. To get around this, specify this ENV variable:<code>EXTERNAL_DB_HOST: <customername>-database.presageanalytics.com</code>. Make sure the URL matches the one in the Crystal Server config. Apparently, SMB DB URLs will always have <code>-database</code> in them since the SMB docker containers don't run on the same iron as MySQL.

As of 02/03/2025, there's also Bartlett, which had some issues setting it up related to SSL. Brian fixed it, I'm not sure what he did. I think they're also set up slightly differently than Culligan GI

==== Self-Hosted ====

If they're okay hitting our Crystal Server, we just need to make sure that their database can be reached on Bunnahabhain, then the setup is the same as a hosted yard.

If not, we'll have to deploy it to a Windows server they control, and set the <code>REPORT_SERVER_URI</code> ENV variable in the API to the proper URI. Presage API will have to be able to reach <code><The Server URL>/process_report</code> in order to generate the reports

=== Enterprise Web/API ===

If we host the customer, we should just set them up on our Crystal Server. Follow the general steps for configuring them in the Crystal Server config.json, then set some ENV variables in Portainer:

* <code>REPORT_SERVER_URI: http://print.itrackchromium.com</code>
* <code>EXTERNAL_DB_HOST: example-url.itrackenterprise.com</code>

WG, UT&W, & QBT are currently (07/08/25) the only EE customers with the web report viewer on, and they also had to have the caPath set in the crystal server config to the old/not-2024 ca cert. Not sure if that'll be true for other EE customers, but it was for them.

If they're self hosted, and don't want to use our Crystal Server, follow the steps under "Deployment", then set the above ENV variables to the proper values for their setup.

== Updating ==

Not 100% sure since it's been awhile, but I'm pretty sure the process is basically:
1. Build the Crystal Server to an exe again
2. Replace the old exe on BH
3. Restart CrystalServer service

== Deployment ==

For 99% of customers, this section will not apply. But in the event that a self-hosted customer wants to host their own Crystal Server, this is probably how.

* Locate a Windows Server
* Install Report Commander on it
* Run CrystalServerSetup.exe from dl.isoftdata.com, I think this sets up the service to make it run in the background and on startup?
* Get the latest EXE or build a new one from https://github.com/ISoft-Data-Systems/crystal-reports-server and replace the old EXE from the installer
* Restart the CrystalServer service
* Make sure the service is reachable from wherever the Presage API is running
* At this point, they should be able to make a request to <code>serveruri</code>/process_report and get a report back.

== Misc / Notes ==

Housby has Crystal Server deployed to generate invoice PDFs for an ecommerce integration. They're using a version before we compiled it to an exe, so if they ever run into bugs or need an update it will be a little different

Web Report Viewer Troubleshooting

2026-02-02T22:07:04Z

Ckaup: /* Common Errors (Table Mode) */

Web Report Viewer Troubleshooting

2026-02-02T22:05:47Z

Ckaup: /* Common Errors (Table Mode) */

Web Report Viewer Troubleshooting

2026-01-09T18:36:07Z

Ckaup:

Web Report Viewer Troubleshooting

2025-12-05T20:57:26Z

Ckaup: /* Terms */

This article applies to Presage Web and ITrack Chromium. The web Report Viewer will give a general error, error details are logged to the reportqueue table and can be viewed in the "History" (web) or "Print Queue" (desktop) tab of the Report Viewer screen.

== Terms ==

* Crystal Server - the Node.JS application that uses Report Commander to generate the report PDF. Runs on Bunnahabhain. '''This application is not the same as Report Queue.'''
* Report Commander - command line application used to generate report PDFs by the Crystal Server (and Report Queue)
* Report Queue - python application that reads from reportqueue table to send emails and print to a printer. '''Report Queue is separate from Crystal Server, and the two systems do not interact.'''
* reportqueue - a table in the database that logs report runs.
* reportparameter - a table in the database that associates parameters to reports

== Common Errors ==

=== Error Running Report ===

This means that Report Commander encountered an error running the report. If you get this error, check the reportqueue error for a more detailed error message. Listed below are some common ones.

==== "Missing parameter values" or "Double check the parameters..."====

This means that Report Commander did not receive all required parameters for the report. Often times, the report will run fine on desktop, because the Crystal SDK can "fill in the gaps", while the web Report Viewer cannot, and needs a row in reportparameter for every parameter.

===== Solution =====

Since this is caused by missing rows in the reportparameter table, re-running the adder scripts will generally fix the issue.

If it doesn't, the adder script could be out of date or otherwise missing parameters.

==== Parameter not found in report: <parametername> ====

This means that a report was passed a parameter it doesn't expect.

===== Solution =====

Make sure the report is up to date

==== (I can't remember the error message) ====

Missing / invalid ODBC configuration. I think this presents as "could not connect to the database" or something to that effect.

===== Solution =====

Brian can make sure the ODBC connection is valid, and give Charles the name to check that the ODBC connection name in the Crystal Server config is correct.

==== Invalid Value for <parameter> ====

Report Commander received an invalid value for the specified parameter

=== Invalid Session ===

This error is caused by the Crystal Server failing to verify the session token it was passed.

==== Solution ====

Most likely, if logging out and back in doesn't fix it, this means that the Crystal Server configuration is either missing, or configured with a different database host URL than the API. Charles can check the logs to double check, as well as update the config file. Brian can then restart the Crystal Server service to load the updated configuration.

=== Invalid Report ===

The Crystal Server failed to find the report with the specified name/type. Or, the report is missing its corresponding <code>file</code> data.

=== The file or directory is corrupted and unreadable ===

Once or twice the cached .rpt file on Bunnahabhain was corrupted or something. We fixed it by reuploading the report to the customer's db and deleting the cached .rpt file from <code>\\192.168.5.18\Node\crystal-reports-server\cache</code>

It's possible it was because the D drive was failing. Cache has been moved to M:\report_cache

=== Other Errors ===

<code>Error: WARNING: MYSQL_OPT_RECONNECT is deprecated and will be removed in a future version.</code> - Disable "Auto Reconnect" on ODBC. Presents as "Unkown Error" or "Internal Server Error" in the UI

== Common Errors (Table Mode)==

This table will hold the answers to (probably) any error you will encounter running reports in Presage Web

{| class="wikitable" style=""
|+ Common Errors
|-
! style="min-width: 100px;"| Error !! Description !! How to Fix
|-
| Invalid Session. Try logging out and logging back in. || This means that the report server was not able to verify your session. Either your session has expired, or the Crystal Server is not configured for that database. The most likely cause of this is, if logging out and back in doesn't fix it, is that the (generally Presage) customer hasn't been set up on the Crystal Server, or some configuration has changed. || If the config for that customer is missing, then add it matching the template. If it is present, make sure that the Crystal Server and Chromium/Presage API are configured with the same DB URL. Otherwise, check the ODBC connection and DB credentials. Charles can check the logs to double check the URLs are good, as well as update the config file. Brian can then restart the Crystal Server service to load the updated configuration.
|-
| rowspan="4" |Error running report. Double check the report parameters and try again. || This means that Report Commander did not receive the correct amount of parameters for the report. Often times, the report will run fine on desktop, because the Crystal SDK can "fill in the gaps" or ignore extra parameters, while the web Report Viewer cannot, and needs a row in reportparameter for every parameter. Check the <code>Report Viewer > History</code> tab for more error details || Generally, update the report and re-run adders, but '''See Below''' for more details, and check <code>Report Viewer > History</code> for more parameter and error details. If updating the report and adder doesn't fix it, it's possible that they are out of date and need fixed.
|-
| '''"Invalid value for <parameter>"''' means Report Commander received an invalid value for the listed parameter. Usually this just means you forgot to fill a parameter out, but could be caused by by an outdated report / adders. || Make sure all parameters are filled out.
|-
| '''"Parameter not found in report: <parameter>"''' means that a parameter was passed to the report that the report doesn't expect. || If caused by an out-of-date report (more common), update the report. If caused by out-of-date adders, re-run adders.
|-
| '''"Missing parameter values"''' means that the report was not passed all expected parameters. Normally, this is because a parameter was added to the report, and the adders are out of date. || Re-run adders.
|-
|| (I can't remember the error message) || Missing / invalid ODBC configuration. I think this presents as "could not connect to the database" or something to that effect. Sometimes it'll give you a "database vendor code" just like ITrack desktop. || Depending on the error code, Brian can make sure the ODBC connection is valid, and give Charles the name to check that the ODBC connection name in the Crystal Server config is correct. But some error codes like 1064 are unrelated to the odbc setup
|-
|| Invalid Report || The Crystal Server failed to find the report with the specified name/type. || Make sure the report exists in the customer database with the given name and type, and a valid <code>report.fileid</code>. In Presage, there used to be a bug where running reports with a non-English language selected would fail with this error.
|-
|| The file or directory is corrupted and unreadable || This would come up every so often because the D drive on Bunnahabhain was failing. It shouldn't happen anymore. || It shouldn't happen again, but if it does, delete the cached report file from <code>M:\report_cache</code> on Bunnahabhain. Maybe reupload the report if it persists after that.
|-
|| Database logon failed || ODBC could not connect to the database || Ask Brian (or maybe someone else from @Systems) to double check the ODBC connection on Bunnahabhain for that customer
|-
|| <code>Database Vendor Code (code)</code> || There was some MySQL error. Look up the error code. || Might depend on the error code, but it's probably because of a bad query in the report. Reupload report.
|-
|| <code>Internal Server Error</code> || You're probably on a version of EEW that doesn't forward the error to the client properly. || Check Report Viewer > History to see the actual error
|}

== Logs ==

The log file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\crystalserverservice.log</code>

A normal log entry for a report job looks like this:

<pre>
Connection created for 'hosteddb-southeast.isoftdata.com.373487'
args [
'-report="D:\\Node\\crystal-reports-server\\cache\\A95AC82D42C7A2A9AFF9F720DA5F3159.rpt"',
'-login!={server:reporting_hosted_southeast}{database:373487}',
'-exportfile="D:\\Node\\crystal-reports-server\\cache\\output\\default_invoice_2024-12-03T19-20-25.872Z.pdf"',
'-exportformat="PDF"',
'-namedparameters invoicenum="5150"'
]
Destroying connection for 'hosteddb-southeast.isoftdata.com.373487'
</pre>

If you see a message like this, then the Crystal Server (not ODBC) failed to connect to the database, and there will probably be a logged request body right below it. The logged request body should have the db host sent from the application, which can be compared to the valid hosts in the config file

<pre>
Destroying connection for 'iceriver.presageanalytics.com.UNKNOWN DATABASE'
</pre>

The most common errors you'll see start like this and will show the command used to run Report Commander as well as a more-detailed error message in a mess of JSON.

<pre>
ReportError: A Report Commander error has occurred
</pre>

== Configuration ==

This will go over how to configure a customer on the Crystal Server, not so much how to deploy and configure a new Crystal Server.

The config file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\config.json</code>

Generally, you just need to set the host, user, password, and odbc data sources for a new connection. However, host MUST be unique, and MUST match the ITrack/Presage server config, as that's what's used to look up the rest of the connection info. Most of the time you can just add another entry to the JSON, like so

<code><pre>{
"host": "HOST",
"user": "USER",
"password": "PASSWORD",
"odbcDataSource": "ODBC DATA SOURCE NAME"
}</pre></code>

In some cases you might also need to set the <code>caPath</code>, <code>certPath</code>, <code>keyPath</code> properties depending on the SSL config. See other configured hosts for examples.

After adding to the JSON, restart the <code>CrystalServer</code> service to apply any changes. See below for more product-specific details.

=== Chromium ===

Does not have to be configured per-customer. One config per VM. The users have more security and so they use more of the SSL options than other users

=== Presage Web/API ===

<code>REPORT_SERVER_URI</code> specifies the report server URI used by the server, and <code>MYSQL_HOST</code> specifies the DB host. <code>EXTERNAL_DB_HOST</code> will be sent to the Crystal Server instead of <code>MYSQL_HOST</code>, if specified. '''Either <code>MYSQL_HOST</code> or <code>EXTERNAL_DB_HOST</code> MUST match the <code>host</code> in the Crystal Server config file or it will not work!'''

==== SMB ====

Currently (12/04/2024), Culligan GI is the only Presage SMB customer, and was configured individually. Maybe in the future, Presage SMB will work like Chromium and just have one config per VM, but that's not currently the case.

Since the setup for SMB clients is slightly different, the <code>MYSQL_HOST</code> is an "internal" IP, but we need an external host that matches what the Crystal Server knows. To get around this, specify this ENV variable:<code>EXTERNAL_DB_HOST: <customername>-database.presageanalytics.com</code>. Make sure the URL matches the one in the Crystal Server config. Apparently, SMB DB URLs will always have <code>-database</code> in them since the SMB docker containers don't run on the same iron as MySQL.

As of 02/03/2025, there's also Bartlett, which had some issues setting it up related to SSL. Brian fixed it, I'm not sure what he did. I think they're also set up slightly differently than Culligan GI

==== Self-Hosted ====

If they're okay hitting our Crystal Server, we just need to make sure that their database can be reached on Bunnahabhain, then the setup is the same as a hosted yard.

If not, we'll have to deploy it to a Windows server they control, and set the <code>REPORT_SERVER_URI</code> ENV variable in the API to the proper URI. Presage API will have to be able to reach <code><The Server URL>/process_report</code> in order to generate the reports

=== Enterprise Web/API ===

If we host the customer, we should just set them up on our Crystal Server. Follow the general steps for configuring them in the Crystal Server config.json, then set some ENV variables in Portainer:

* <code>REPORT_SERVER_URI: http://print.itrackchromium.com</code>
* <code>EXTERNAL_DB_HOST: example-url.itrackenterprise.com</code>

WG, UT&W, & QBT are currently (07/08/25) the only EE customers with the web report viewer on, and they also had to have the caPath set in the crystal server config to the old/not-2024 ca cert. Not sure if that'll be true for other EE customers, but it was for them.

If they're self hosted, and don't want to use our Crystal Server, follow the steps under "Deployment", then set the above ENV variables to the proper values for their setup.

== Updating ==

Not 100% sure since it's been awhile, but I'm pretty sure the process is basically:
1. Build the Crystal Server to an exe again
2. Replace the old exe on BH
3. Restart CrystalServer service

== Deployment ==

For 99% of customers, this section will not apply. But in the event that a self-hosted customer wants to host their own Crystal Server, this is probably how.

* Locate a Windows Server
* Install Report Commander on it
* Run CrystalServerSetup.exe from dl.isoftdata.com, I think this sets up the service to make it run in the background and on startup?
* Get the latest EXE or build a new one from https://github.com/ISoft-Data-Systems/crystal-reports-server and replace the old EXE from the installer
* Restart the CrystalServer service
* Make sure the service is reachable from wherever the Presage API is running
* At this point, they should be able to make a request to <code>serveruri</code>/process_report and get a report back.

== Misc / Notes ==

Housby has Crystal Server deployed to generate invoice PDFs for an ecommerce integration. They're using a version before we compiled it to an exe, so if they ever run into bugs or need an update it will be a little different

Web Report Viewer Troubleshooting

2025-12-05T20:50:34Z

Ckaup: /* Common Errors (Table Mode) */

This article applies to Presage Web and ITrack Chromium. The web Report Viewer will give a general error, error details are logged to the reportqueue table and can be viewed in the "History" (web) or "Print Queue" (desktop) tab of the Report Viewer screen.

== Terms ==

* Crystal Server - the Node.JS application that uses Report Commander to generate the report PDF. Runs on Bunnahabhain
* Report Commander - command line application used to generate report PDFs by the Crystal Server (and Report Queue)
* Report Queue - python application that reads from reportqueue table to send emails and print to a printer. '''Report Queue is separate from Crystal Server, and the two systems do not interact.'''
* reportqueue - a table in the database that logs report runs.
* reportparameter - a table in the database that associates parameters to reports

== Common Errors ==

=== Error Running Report ===

This means that Report Commander encountered an error running the report. If you get this error, check the reportqueue error for a more detailed error message. Listed below are some common ones.

==== "Missing parameter values" or "Double check the parameters..."====

This means that Report Commander did not receive all required parameters for the report. Often times, the report will run fine on desktop, because the Crystal SDK can "fill in the gaps", while the web Report Viewer cannot, and needs a row in reportparameter for every parameter.

===== Solution =====

Since this is caused by missing rows in the reportparameter table, re-running the adder scripts will generally fix the issue.

If it doesn't, the adder script could be out of date or otherwise missing parameters.

==== Parameter not found in report: <parametername> ====

This means that a report was passed a parameter it doesn't expect.

===== Solution =====

Make sure the report is up to date

==== (I can't remember the error message) ====

Missing / invalid ODBC configuration. I think this presents as "could not connect to the database" or something to that effect.

===== Solution =====

Brian can make sure the ODBC connection is valid, and give Charles the name to check that the ODBC connection name in the Crystal Server config is correct.

==== Invalid Value for <parameter> ====

Report Commander received an invalid value for the specified parameter

=== Invalid Session ===

This error is caused by the Crystal Server failing to verify the session token it was passed.

==== Solution ====

Most likely, if logging out and back in doesn't fix it, this means that the Crystal Server configuration is either missing, or configured with a different database host URL than the API. Charles can check the logs to double check, as well as update the config file. Brian can then restart the Crystal Server service to load the updated configuration.

=== Invalid Report ===

The Crystal Server failed to find the report with the specified name/type. Or, the report is missing its corresponding <code>file</code> data.

=== The file or directory is corrupted and unreadable ===

Once or twice the cached .rpt file on Bunnahabhain was corrupted or something. We fixed it by reuploading the report to the customer's db and deleting the cached .rpt file from <code>\\192.168.5.18\Node\crystal-reports-server\cache</code>

It's possible it was because the D drive was failing. Cache has been moved to M:\report_cache

=== Other Errors ===

<code>Error: WARNING: MYSQL_OPT_RECONNECT is deprecated and will be removed in a future version.</code> - Disable "Auto Reconnect" on ODBC. Presents as "Unkown Error" or "Internal Server Error" in the UI

== Common Errors (Table Mode)==

This table will hold the answers to (probably) any error you will encounter running reports in Presage Web

{| class="wikitable" style=""
|+ Common Errors
|-
! style="min-width: 100px;"| Error !! Description !! How to Fix
|-
| Invalid Session. Try logging out and logging back in. || This means that the report server was not able to verify your session. Either your session has expired, or the Crystal Server is not configured for that database. The most likely cause of this is, if logging out and back in doesn't fix it, is that the (generally Presage) customer hasn't been set up on the Crystal Server, or some configuration has changed. || If the config for that customer is missing, then add it matching the template. If it is present, make sure that the Crystal Server and Chromium/Presage API are configured with the same DB URL. Otherwise, check the ODBC connection and DB credentials. Charles can check the logs to double check the URLs are good, as well as update the config file. Brian can then restart the Crystal Server service to load the updated configuration.
|-
| rowspan="4" |Error running report. Double check the report parameters and try again. || This means that Report Commander did not receive the correct amount of parameters for the report. Often times, the report will run fine on desktop, because the Crystal SDK can "fill in the gaps" or ignore extra parameters, while the web Report Viewer cannot, and needs a row in reportparameter for every parameter. Check the <code>Report Viewer > History</code> tab for more error details || Generally, update the report and re-run adders, but '''See Below''' for more details, and check <code>Report Viewer > History</code> for more parameter and error details. If updating the report and adder doesn't fix it, it's possible that they are out of date and need fixed.
|-
| '''"Invalid value for <parameter>"''' means Report Commander received an invalid value for the listed parameter. Usually this just means you forgot to fill a parameter out, but could be caused by by an outdated report / adders. || Make sure all parameters are filled out.
|-
| '''"Parameter not found in report: <parameter>"''' means that a parameter was passed to the report that the report doesn't expect. || If caused by an out-of-date report (more common), update the report. If caused by out-of-date adders, re-run adders.
|-
| '''"Missing parameter values"''' means that the report was not passed all expected parameters. Normally, this is because a parameter was added to the report, and the adders are out of date. || Re-run adders.
|-
|| (I can't remember the error message) || Missing / invalid ODBC configuration. I think this presents as "could not connect to the database" or something to that effect. Sometimes it'll give you a "database vendor code" just like ITrack desktop. || Depending on the error code, Brian can make sure the ODBC connection is valid, and give Charles the name to check that the ODBC connection name in the Crystal Server config is correct. But some error codes like 1064 are unrelated to the odbc setup
|-
|| Invalid Report || The Crystal Server failed to find the report with the specified name/type. || Make sure the report exists in the customer database with the given name and type, and a valid <code>report.fileid</code>. In Presage, there used to be a bug where running reports with a non-English language selected would fail with this error.
|-
|| The file or directory is corrupted and unreadable || This would come up every so often because the D drive on Bunnahabhain was failing. It shouldn't happen anymore. || It shouldn't happen again, but if it does, delete the cached report file from <code>M:\report_cache</code> on Bunnahabhain. Maybe reupload the report if it persists after that.
|-
|| Database logon failed || ODBC could not connect to the database || Ask Brian (or maybe someone else from @Systems) to double check the ODBC connection on Bunnahabhain for that customer
|-
|| <code>Database Vendor Code (code)</code> || There was some MySQL error. Look up the error code. || Might depend on the error code, but it's probably because of a bad query in the report. Reupload report.
|-
|| <code>Internal Server Error</code> || You're probably on a version of EEW that doesn't forward the error to the client properly. || Check Report Viewer > History to see the actual error
|}

== Logs ==

The log file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\crystalserverservice.log</code>

A normal log entry for a report job looks like this:

<pre>
Connection created for 'hosteddb-southeast.isoftdata.com.373487'
args [
'-report="D:\\Node\\crystal-reports-server\\cache\\A95AC82D42C7A2A9AFF9F720DA5F3159.rpt"',
'-login!={server:reporting_hosted_southeast}{database:373487}',
'-exportfile="D:\\Node\\crystal-reports-server\\cache\\output\\default_invoice_2024-12-03T19-20-25.872Z.pdf"',
'-exportformat="PDF"',
'-namedparameters invoicenum="5150"'
]
Destroying connection for 'hosteddb-southeast.isoftdata.com.373487'
</pre>

If you see a message like this, then the Crystal Server (not ODBC) failed to connect to the database, and there will probably be a logged request body right below it. The logged request body should have the db host sent from the application, which can be compared to the valid hosts in the config file

<pre>
Destroying connection for 'iceriver.presageanalytics.com.UNKNOWN DATABASE'
</pre>

The most common errors you'll see start like this and will show the command used to run Report Commander as well as a more-detailed error message in a mess of JSON.

<pre>
ReportError: A Report Commander error has occurred
</pre>

== Configuration ==

This will go over how to configure a customer on the Crystal Server, not so much how to deploy and configure a new Crystal Server.

The config file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\config.json</code>

Generally, you just need to set the host, user, password, and odbc data sources for a new connection. However, host MUST be unique, and MUST match the ITrack/Presage server config, as that's what's used to look up the rest of the connection info. Most of the time you can just add another entry to the JSON, like so

<code><pre>{
"host": "HOST",
"user": "USER",
"password": "PASSWORD",
"odbcDataSource": "ODBC DATA SOURCE NAME"
}</pre></code>

In some cases you might also need to set the <code>caPath</code>, <code>certPath</code>, <code>keyPath</code> properties depending on the SSL config. See other configured hosts for examples.

After adding to the JSON, restart the <code>CrystalServer</code> service to apply any changes. See below for more product-specific details.

=== Chromium ===

Does not have to be configured per-customer. One config per VM. The users have more security and so they use more of the SSL options than other users

=== Presage Web/API ===

<code>REPORT_SERVER_URI</code> specifies the report server URI used by the server, and <code>MYSQL_HOST</code> specifies the DB host. <code>EXTERNAL_DB_HOST</code> will be sent to the Crystal Server instead of <code>MYSQL_HOST</code>, if specified. '''Either <code>MYSQL_HOST</code> or <code>EXTERNAL_DB_HOST</code> MUST match the <code>host</code> in the Crystal Server config file or it will not work!'''

==== SMB ====

Currently (12/04/2024), Culligan GI is the only Presage SMB customer, and was configured individually. Maybe in the future, Presage SMB will work like Chromium and just have one config per VM, but that's not currently the case.

Since the setup for SMB clients is slightly different, the <code>MYSQL_HOST</code> is an "internal" IP, but we need an external host that matches what the Crystal Server knows. To get around this, specify this ENV variable:<code>EXTERNAL_DB_HOST: <customername>-database.presageanalytics.com</code>. Make sure the URL matches the one in the Crystal Server config. Apparently, SMB DB URLs will always have <code>-database</code> in them since the SMB docker containers don't run on the same iron as MySQL.

As of 02/03/2025, there's also Bartlett, which had some issues setting it up related to SSL. Brian fixed it, I'm not sure what he did. I think they're also set up slightly differently than Culligan GI

==== Self-Hosted ====

If they're okay hitting our Crystal Server, we just need to make sure that their database can be reached on Bunnahabhain, then the setup is the same as a hosted yard.

If not, we'll have to deploy it to a Windows server they control, and set the <code>REPORT_SERVER_URI</code> ENV variable in the API to the proper URI. Presage API will have to be able to reach <code><The Server URL>/process_report</code> in order to generate the reports

=== Enterprise Web/API ===

If we host the customer, we should just set them up on our Crystal Server. Follow the general steps for configuring them in the Crystal Server config.json, then set some ENV variables in Portainer:

* <code>REPORT_SERVER_URI: http://print.itrackchromium.com</code>
* <code>EXTERNAL_DB_HOST: example-url.itrackenterprise.com</code>

WG, UT&W, & QBT are currently (07/08/25) the only EE customers with the web report viewer on, and they also had to have the caPath set in the crystal server config to the old/not-2024 ca cert. Not sure if that'll be true for other EE customers, but it was for them.

If they're self hosted, and don't want to use our Crystal Server, follow the steps under "Deployment", then set the above ENV variables to the proper values for their setup.

== Updating ==

Not 100% sure since it's been awhile, but I'm pretty sure the process is basically:
1. Build the Crystal Server to an exe again
2. Replace the old exe on BH
3. Restart CrystalServer service

== Deployment ==

For 99% of customers, this section will not apply. But in the event that a self-hosted customer wants to host their own Crystal Server, this is probably how.

* Locate a Windows Server
* Install Report Commander on it
* Run CrystalServerSetup.exe from dl.isoftdata.com, I think this sets up the service to make it run in the background and on startup?
* Get the latest EXE or build a new one from https://github.com/ISoft-Data-Systems/crystal-reports-server and replace the old EXE from the installer
* Restart the CrystalServer service
* Make sure the service is reachable from wherever the Presage API is running
* At this point, they should be able to make a request to <code>serveruri</code>/process_report and get a report back.

== Misc / Notes ==

Housby has Crystal Server deployed to generate invoice PDFs for an ecommerce integration. They're using a version before we compiled it to an exe, so if they ever run into bugs or need an update it will be a little different

Web Report Viewer Troubleshooting

2025-12-05T20:47:02Z

Ckaup: /* Common Errors (Table Mode) */

This article applies to Presage Web and ITrack Chromium. The web Report Viewer will give a general error, error details are logged to the reportqueue table and can be viewed in the "History" (web) or "Print Queue" (desktop) tab of the Report Viewer screen.

== Terms ==

* Crystal Server - the Node.JS application that uses Report Commander to generate the report PDF. Runs on Bunnahabhain
* Report Commander - command line application used to generate report PDFs by the Crystal Server (and Report Queue)
* Report Queue - python application that reads from reportqueue table to send emails and print to a printer. '''Report Queue is separate from Crystal Server, and the two systems do not interact.'''
* reportqueue - a table in the database that logs report runs.
* reportparameter - a table in the database that associates parameters to reports

== Common Errors ==

=== Error Running Report ===

This means that Report Commander encountered an error running the report. If you get this error, check the reportqueue error for a more detailed error message. Listed below are some common ones.

==== "Missing parameter values" or "Double check the parameters..."====

This means that Report Commander did not receive all required parameters for the report. Often times, the report will run fine on desktop, because the Crystal SDK can "fill in the gaps", while the web Report Viewer cannot, and needs a row in reportparameter for every parameter.

===== Solution =====

Since this is caused by missing rows in the reportparameter table, re-running the adder scripts will generally fix the issue.

If it doesn't, the adder script could be out of date or otherwise missing parameters.

==== Parameter not found in report: <parametername> ====

This means that a report was passed a parameter it doesn't expect.

===== Solution =====

Make sure the report is up to date

==== (I can't remember the error message) ====

Missing / invalid ODBC configuration. I think this presents as "could not connect to the database" or something to that effect.

===== Solution =====

Brian can make sure the ODBC connection is valid, and give Charles the name to check that the ODBC connection name in the Crystal Server config is correct.

==== Invalid Value for <parameter> ====

Report Commander received an invalid value for the specified parameter

=== Invalid Session ===

This error is caused by the Crystal Server failing to verify the session token it was passed.

==== Solution ====

Most likely, if logging out and back in doesn't fix it, this means that the Crystal Server configuration is either missing, or configured with a different database host URL than the API. Charles can check the logs to double check, as well as update the config file. Brian can then restart the Crystal Server service to load the updated configuration.

=== Invalid Report ===

The Crystal Server failed to find the report with the specified name/type. Or, the report is missing its corresponding <code>file</code> data.

=== The file or directory is corrupted and unreadable ===

Once or twice the cached .rpt file on Bunnahabhain was corrupted or something. We fixed it by reuploading the report to the customer's db and deleting the cached .rpt file from <code>\\192.168.5.18\Node\crystal-reports-server\cache</code>

It's possible it was because the D drive was failing. Cache has been moved to M:\report_cache

=== Other Errors ===

<code>Error: WARNING: MYSQL_OPT_RECONNECT is deprecated and will be removed in a future version.</code> - Disable "Auto Reconnect" on ODBC. Presents as "Unkown Error" or "Internal Server Error" in the UI

== Common Errors (Table Mode)==

{| class="wikitable" style=""
|+ Common Errors
|-
! style="min-width: 100px;"| Error !! Description !! How to Fix
|-
| Invalid Session. Try logging out and logging back in. || This means that the report server was not able to verify your session. Either your session has expired, or the Crystal Server is not configured for that database. The most likely cause of this is, if logging out and back in doesn't fix it, is that the (generally Presage) customer hasn't been set up on the Crystal Server, or some configuration has changed. || If the config for that customer is missing, then add it matching the template. If it is present, make sure that the Crystal Server and Chromium/Presage API are configured with the same DB URL. Otherwise, check the ODBC connection and DB credentials. Charles can check the logs to double check the URLs are good, as well as update the config file. Brian can then restart the Crystal Server service to load the updated configuration.
|-
| rowspan="4" |Error running report. Double check the report parameters and try again. || This means that Report Commander did not receive the correct amount of parameters for the report. Often times, the report will run fine on desktop, because the Crystal SDK can "fill in the gaps" or ignore extra parameters, while the web Report Viewer cannot, and needs a row in reportparameter for every parameter. Check the <code>Report Viewer > History</code> tab for more error details || Generally, update the report and re-run adders, but '''See Below''' for more details, and check <code>Report Viewer > History</code> for more parameter and error details. If updating the report and adder doesn't fix it, it's possible that they are out of date and need fixed.
|-
| '''"Invalid value for <parameter>"''' means Report Commander received an invalid value for the listed parameter. Usually this just means you forgot to fill a parameter out, but could be caused by by an outdated report / adders. || Make sure all parameters are filled out.
|-
| '''"Parameter not found in report: <parameter>"''' means that a parameter was passed to the report that the report doesn't expect. || If caused by an out-of-date report (more common), update the report. If caused by out-of-date adders, re-run adders.
|-
| '''"Missing parameter values"''' means that the report was not passed all expected parameters. Normally, this is because a parameter was added to the report, and the adders are out of date. || Re-run adders.
|-
|| (I can't remember the error message) || Missing / invalid ODBC configuration. I think this presents as "could not connect to the database" or something to that effect. Sometimes it'll give you a "database vendor code" just like ITrack desktop. || Depending on the error code, Brian can make sure the ODBC connection is valid, and give Charles the name to check that the ODBC connection name in the Crystal Server config is correct. But some error codes like 1064 are unrelated to the odbc setup
|-
|| Invalid Report || The Crystal Server failed to find the report with the specified name/type. || Make sure the report exists in the customer database with the given name and type, and a valid <code>report.fileid</code>. In Presage, there used to be a bug where running reports with a non-English language selected would fail with this error.
|-
|| The file or directory is corrupted and unreadable || This would come up every so often because the D drive on Bunnahabhain was failing. It shouldn't happen anymore. || It shouldn't happen again, but if it does, delete the cached report file from <code>M:\report_cache</code> on Bunnahabhain. Maybe reupload the report if it persists after that.
|-
|| Database logon failed || ODBC could not connect to the database || Ask Brian (or maybe someone else from @Systems) to double check the ODBC connection on Bunnahabhain for that customer
|-
|| <code>Database Vendor Code (code)</code> || There was some MySQL error. Look up the error code. || Might depend on the error code, but it's probably because of a bad query in the report. Reupload report.
|-
|| <code>Internal Server Error</code> || You're probably on a version of EEW that doesn't forward the error to the client properly. || Check Report Viewer > History to see the actual error
|}

== Logs ==

The log file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\crystalserverservice.log</code>

A normal log entry for a report job looks like this:

<pre>
Connection created for 'hosteddb-southeast.isoftdata.com.373487'
args [
'-report="D:\\Node\\crystal-reports-server\\cache\\A95AC82D42C7A2A9AFF9F720DA5F3159.rpt"',
'-login!={server:reporting_hosted_southeast}{database:373487}',
'-exportfile="D:\\Node\\crystal-reports-server\\cache\\output\\default_invoice_2024-12-03T19-20-25.872Z.pdf"',
'-exportformat="PDF"',
'-namedparameters invoicenum="5150"'
]
Destroying connection for 'hosteddb-southeast.isoftdata.com.373487'
</pre>

If you see a message like this, then the Crystal Server (not ODBC) failed to connect to the database, and there will probably be a logged request body right below it. The logged request body should have the db host sent from the application, which can be compared to the valid hosts in the config file

<pre>
Destroying connection for 'iceriver.presageanalytics.com.UNKNOWN DATABASE'
</pre>

The most common errors you'll see start like this and will show the command used to run Report Commander as well as a more-detailed error message in a mess of JSON.

<pre>
ReportError: A Report Commander error has occurred
</pre>

== Configuration ==

This will go over how to configure a customer on the Crystal Server, not so much how to deploy and configure a new Crystal Server.

The config file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\config.json</code>

Generally, you just need to set the host, user, password, and odbc data sources for a new connection. However, host MUST be unique, and MUST match the ITrack/Presage server config, as that's what's used to look up the rest of the connection info. Most of the time you can just add another entry to the JSON, like so

<code><pre>{
"host": "HOST",
"user": "USER",
"password": "PASSWORD",
"odbcDataSource": "ODBC DATA SOURCE NAME"
}</pre></code>

In some cases you might also need to set the <code>caPath</code>, <code>certPath</code>, <code>keyPath</code> properties depending on the SSL config. See other configured hosts for examples.

After adding to the JSON, restart the <code>CrystalServer</code> service to apply any changes. See below for more product-specific details.

=== Chromium ===

Does not have to be configured per-customer. One config per VM. The users have more security and so they use more of the SSL options than other users

=== Presage Web/API ===

<code>REPORT_SERVER_URI</code> specifies the report server URI used by the server, and <code>MYSQL_HOST</code> specifies the DB host. <code>EXTERNAL_DB_HOST</code> will be sent to the Crystal Server instead of <code>MYSQL_HOST</code>, if specified. '''Either <code>MYSQL_HOST</code> or <code>EXTERNAL_DB_HOST</code> MUST match the <code>host</code> in the Crystal Server config file or it will not work!'''

==== SMB ====

Currently (12/04/2024), Culligan GI is the only Presage SMB customer, and was configured individually. Maybe in the future, Presage SMB will work like Chromium and just have one config per VM, but that's not currently the case.

Since the setup for SMB clients is slightly different, the <code>MYSQL_HOST</code> is an "internal" IP, but we need an external host that matches what the Crystal Server knows. To get around this, specify this ENV variable:<code>EXTERNAL_DB_HOST: <customername>-database.presageanalytics.com</code>. Make sure the URL matches the one in the Crystal Server config. Apparently, SMB DB URLs will always have <code>-database</code> in them since the SMB docker containers don't run on the same iron as MySQL.

As of 02/03/2025, there's also Bartlett, which had some issues setting it up related to SSL. Brian fixed it, I'm not sure what he did. I think they're also set up slightly differently than Culligan GI

==== Self-Hosted ====

If they're okay hitting our Crystal Server, we just need to make sure that their database can be reached on Bunnahabhain, then the setup is the same as a hosted yard.

If not, we'll have to deploy it to a Windows server they control, and set the <code>REPORT_SERVER_URI</code> ENV variable in the API to the proper URI. Presage API will have to be able to reach <code><The Server URL>/process_report</code> in order to generate the reports

=== Enterprise Web/API ===

If we host the customer, we should just set them up on our Crystal Server. Follow the general steps for configuring them in the Crystal Server config.json, then set some ENV variables in Portainer:

* <code>REPORT_SERVER_URI: http://print.itrackchromium.com</code>
* <code>EXTERNAL_DB_HOST: example-url.itrackenterprise.com</code>

WG, UT&W, & QBT are currently (07/08/25) the only EE customers with the web report viewer on, and they also had to have the caPath set in the crystal server config to the old/not-2024 ca cert. Not sure if that'll be true for other EE customers, but it was for them.

If they're self hosted, and don't want to use our Crystal Server, follow the steps under "Deployment", then set the above ENV variables to the proper values for their setup.

== Updating ==

Not 100% sure since it's been awhile, but I'm pretty sure the process is basically:
1. Build the Crystal Server to an exe again
2. Replace the old exe on BH
3. Restart CrystalServer service

== Deployment ==

For 99% of customers, this section will not apply. But in the event that a self-hosted customer wants to host their own Crystal Server, this is probably how.

* Locate a Windows Server
* Install Report Commander on it
* Run CrystalServerSetup.exe from dl.isoftdata.com, I think this sets up the service to make it run in the background and on startup?
* Get the latest EXE or build a new one from https://github.com/ISoft-Data-Systems/crystal-reports-server and replace the old EXE from the installer
* Restart the CrystalServer service
* Make sure the service is reachable from wherever the Presage API is running
* At this point, they should be able to make a request to <code>serveruri</code>/process_report and get a report back.

== Misc / Notes ==

Housby has Crystal Server deployed to generate invoice PDFs for an ecommerce integration. They're using a version before we compiled it to an exe, so if they ever run into bugs or need an update it will be a little different

Web Report Viewer Troubleshooting

2025-09-03T15:24:48Z

Ckaup: /* Configuration */

This article applies to Presage Web and ITrack Chromium. The web Report Viewer will give a general error, error details are logged to the reportqueue table and can be viewed in the "History" (web) or "Print Queue" (desktop) tab of the Report Viewer screen.

== Terms ==

* Crystal Server - the Node.JS application that uses Report Commander to generate the report PDF. Runs on Bunnahabhain
* Report Commander - command line application used to generate report PDFs by the Crystal Server (and Report Queue)
* Report Queue - python application that reads from reportqueue table to send emails and print to a printer. '''Report Queue is separate from Crystal Server, and the two systems do not interact.'''
* reportqueue - a table in the database that logs report runs.
* reportparameter - a table in the database that associates parameters to reports

== Common Errors ==

=== Error Running Report ===

This means that Report Commander encountered an error running the report. If you get this error, check the reportqueue error for a more detailed error message. Listed below are some common ones.

==== "Missing parameter values" or "Double check the parameters..."====

This means that Report Commander did not receive all required parameters for the report. Often times, the report will run fine on desktop, because the Crystal SDK can "fill in the gaps", while the web Report Viewer cannot, and needs a row in reportparameter for every parameter.

===== Solution =====

Since this is caused by missing rows in the reportparameter table, re-running the adder scripts will generally fix the issue.

If it doesn't, the adder script could be out of date or otherwise missing parameters.

==== Parameter not found in report: <parametername> ====

This means that a report was passed a parameter it doesn't expect.

===== Solution =====

Make sure the report is up to date

==== (I can't remember the error message) ====

Missing / invalid ODBC configuration. I think this presents as "could not connect to the database" or something to that effect.

===== Solution =====

Brian can make sure the ODBC connection is valid, and give Charles the name to check that the ODBC connection name in the Crystal Server config is correct.

==== Invalid Value for <parameter> ====

Report Commander received an invalid value for the specified parameter

=== Invalid Session ===

This error is caused by the Crystal Server failing to verify the session token it was passed.

==== Solution ====

Most likely, if logging out and back in doesn't fix it, this means that the Crystal Server configuration is either missing, or configured with a different database host URL than the API. Charles can check the logs to double check, as well as update the config file. Brian can then restart the Crystal Server service to load the updated configuration.

=== Invalid Report ===

The Crystal Server failed to find the report with the specified name/type. Or, the report is missing its corresponding <code>file</code> data.

=== The file or directory is corrupted and unreadable ===

Once or twice the cached .rpt file on Bunnahabhain was corrupted or something. We fixed it by reuploading the report to the customer's db and deleting the cached .rpt file from <code>\\192.168.5.18\Node\crystal-reports-server\cache</code>

It's possible it was because the D drive was failing. Cache has been moved to M:\report_cache

=== Other Errors ===

<code>Error: WARNING: MYSQL_OPT_RECONNECT is deprecated and will be removed in a future version.</code> - Disable "Auto Reconnect" on ODBC. Presents as "Unkown Error" or "Internal Server Error" in the UI

== Common Errors (Table Mode)==

{| class="wikitable" style=""
|+ Common Errors
|-
! style="min-width: 100px;"| Error !! Description !! How to Fix
|-
| Invalid Session. Try logging out and logging back in. || This means that the report server was not able to verify your session. Either your session has expired, or the Crystal Server is not configured for that database. The most likely cause of this is, if logging out and back in doesn't fix it, is that the (generally Presage) customer hasn't been set up on the Crystal Server, or some configuration has changed. || If the config for that customer is missing, then add it matching the template. If it is present, make sure that the Crystal Server and Chromium/Presage API are configured with the same DB URL. Otherwise, check the ODBC connection and DB credentials. Charles can check the logs to double check the URLs are good, as well as update the config file. Brian can then restart the Crystal Server service to load the updated configuration.
|-
| rowspan="4" |Error running report. Double check the report parameters and try again. || This means that Report Commander did not receive the correct amount of parameters for the report. Often times, the report will run fine on desktop, because the Crystal SDK can "fill in the gaps" or ignore extra parameters, while the web Report Viewer cannot, and needs a row in reportparameter for every parameter. Check the <code>Report Viewer > History</code> tab for more error details || Generally, update the report and re-run adders, but '''See Below''' for more details, and check <code>Report Viewer > History</code> for more parameter and error details. If updating the report and adder doesn't fix it, it's possible that they are out of date and need fixed.
|-
| '''"Invalid value for <parameter>"''' means Report Commander received an invalid value for the listed parameter. Usually this just means you forgot to fill a parameter out, but could be caused by by an outdated report / adders. || Make sure all parameters are filled out.
|-
| '''"Parameter not found in report: <parameter>"''' means that a parameter was passed to the report that the report doesn't expect. || If caused by an out-of-date report (more common), update the report. If caused by out-of-date adders, re-run adders.
|-
| '''"Missing parameter values"''' means that the report was not passed all expected parameters. Normally, this is because a parameter was added to the report, and the adders are out of date. || Re-run adders.
|-
|| (I can't remember the error message) || Missing / invalid ODBC configuration. I think this presents as "could not connect to the database" or something to that effect. Sometimes it'll give you a "database vendor code" just like ITrack desktop. || Depending on the error code, Brian can make sure the ODBC connection is valid, and give Charles the name to check that the ODBC connection name in the Crystal Server config is correct. But some error codes like 1064 are unrelated to the odbc setup
|-
|| Invalid Report || The Crystal Server failed to find the report with the specified name/type. || Make sure the report exists in the customer database with the given name and type, and a valid <code>report.fileid</code>. In Presage, there used to be a bug where running reports with a non-English language selected would fail with this error.
|-
|| The file or directory is corrupted and unreadable || This would come up every so often because the D drive on Bunnahabhain was failing. It shouldn't happen anymore. || It shouldn't happen again, but if it does, delete the cached report file from <code>M:\report_cache</code> on Bunnahabhain. Maybe reupload the report if it persists after that.
|-
|| <code>Database Vendor Code (code)</code> || There was some MySQL error. Look up the error code. || Might depend on the error code, but it's probably because of a bad query in the report. Reupload report.
|-
|| <code>Internal Server Error</code> || You're probably on a version of EEW that doesn't forward the error to the client properly. || Check Report Viewer > History to see the actual error
|}

== Logs ==

The log file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\crystalserverservice.log</code>

A normal log entry for a report job looks like this:

<pre>
Connection created for 'hosteddb-southeast.isoftdata.com.373487'
args [
'-report="D:\\Node\\crystal-reports-server\\cache\\A95AC82D42C7A2A9AFF9F720DA5F3159.rpt"',
'-login!={server:reporting_hosted_southeast}{database:373487}',
'-exportfile="D:\\Node\\crystal-reports-server\\cache\\output\\default_invoice_2024-12-03T19-20-25.872Z.pdf"',
'-exportformat="PDF"',
'-namedparameters invoicenum="5150"'
]
Destroying connection for 'hosteddb-southeast.isoftdata.com.373487'
</pre>

If you see a message like this, then the Crystal Server (not ODBC) failed to connect to the database, and there will probably be a logged request body right below it. The logged request body should have the db host sent from the application, which can be compared to the valid hosts in the config file

<pre>
Destroying connection for 'iceriver.presageanalytics.com.UNKNOWN DATABASE'
</pre>

The most common errors you'll see start like this and will show the command used to run Report Commander as well as a more-detailed error message in a mess of JSON.

<pre>
ReportError: A Report Commander error has occurred
</pre>

== Configuration ==

This will go over how to configure a customer on the Crystal Server, not so much how to deploy and configure a new Crystal Server.

The config file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\config.json</code>

Generally, you just need to set the host, user, password, and odbc data sources for a new connection. However, host MUST be unique, and MUST match the ITrack/Presage server config, as that's what's used to look up the rest of the connection info. Most of the time you can just add another entry to the JSON, like so

<code><pre>{
"host": "HOST",
"user": "USER",
"password": "PASSWORD",
"odbcDataSource": "ODBC DATA SOURCE NAME"
}</pre></code>

In some cases you might also need to set the <code>caPath</code>, <code>certPath</code>, <code>keyPath</code> properties depending on the SSL config. See other configured hosts for examples.

After adding to the JSON, restart the <code>CrystalServer</code> service to apply any changes. See below for more product-specific details.

=== Chromium ===

Does not have to be configured per-customer. One config per VM. The users have more security and so they use more of the SSL options than other users

=== Presage Web/API ===

<code>REPORT_SERVER_URI</code> specifies the report server URI used by the server, and <code>MYSQL_HOST</code> specifies the DB host. <code>EXTERNAL_DB_HOST</code> will be sent to the Crystal Server instead of <code>MYSQL_HOST</code>, if specified. '''Either <code>MYSQL_HOST</code> or <code>EXTERNAL_DB_HOST</code> MUST match the <code>host</code> in the Crystal Server config file or it will not work!'''

==== SMB ====

Currently (12/04/2024), Culligan GI is the only Presage SMB customer, and was configured individually. Maybe in the future, Presage SMB will work like Chromium and just have one config per VM, but that's not currently the case.

Since the setup for SMB clients is slightly different, the <code>MYSQL_HOST</code> is an "internal" IP, but we need an external host that matches what the Crystal Server knows. To get around this, specify this ENV variable:<code>EXTERNAL_DB_HOST: <customername>-database.presageanalytics.com</code>. Make sure the URL matches the one in the Crystal Server config. Apparently, SMB DB URLs will always have <code>-database</code> in them since the SMB docker containers don't run on the same iron as MySQL.

As of 02/03/2025, there's also Bartlett, which had some issues setting it up related to SSL. Brian fixed it, I'm not sure what he did. I think they're also set up slightly differently than Culligan GI

==== Self-Hosted ====

If they're okay hitting our Crystal Server, we just need to make sure that their database can be reached on Bunnahabhain, then the setup is the same as a hosted yard.

If not, we'll have to deploy it to a Windows server they control, and set the <code>REPORT_SERVER_URI</code> ENV variable in the API to the proper URI. Presage API will have to be able to reach <code><The Server URL>/process_report</code> in order to generate the reports

=== Enterprise Web/API ===

If we host the customer, we should just set them up on our Crystal Server. Follow the general steps for configuring them in the Crystal Server config.json, then set some ENV variables in Portainer:

* <code>REPORT_SERVER_URI: http://print.itrackchromium.com</code>
* <code>EXTERNAL_DB_HOST: example-url.itrackenterprise.com</code>

WG, UT&W, & QBT are currently (07/08/25) the only EE customers with the web report viewer on, and they also had to have the caPath set in the crystal server config to the old/not-2024 ca cert. Not sure if that'll be true for other EE customers, but it was for them.

If they're self hosted, and don't want to use our Crystal Server, follow the steps under "Deployment", then set the above ENV variables to the proper values for their setup.

== Updating ==

Not 100% sure since it's been awhile, but I'm pretty sure the process is basically:
1. Build the Crystal Server to an exe again
2. Replace the old exe on BH
3. Restart CrystalServer service

== Deployment ==

For 99% of customers, this section will not apply. But in the event that a self-hosted customer wants to host their own Crystal Server, this is probably how.

* Locate a Windows Server
* Install Report Commander on it
* Run CrystalServerSetup.exe from dl.isoftdata.com, I think this sets up the service to make it run in the background and on startup?
* Get the latest EXE or build a new one from https://github.com/ISoft-Data-Systems/crystal-reports-server and replace the old EXE from the installer
* Restart the CrystalServer service
* Make sure the service is reachable from wherever the Presage API is running
* At this point, they should be able to make a request to <code>serveruri</code>/process_report and get a report back.

== Misc / Notes ==

Housby has Crystal Server deployed to generate invoice PDFs for an ecommerce integration. They're using a version before we compiled it to an exe, so if they ever run into bugs or need an update it will be a little different

Web Report Viewer Troubleshooting

2025-07-08T19:53:10Z

Ckaup: /* Enterprise Web/API */

This article applies to Presage Web and ITrack Chromium. The web Report Viewer will give a general error, error details are logged to the reportqueue table and can be viewed in the "History" (web) or "Print Queue" (desktop) tab of the Report Viewer screen.

== Terms ==

* Crystal Server - the Node.JS application that uses Report Commander to generate the report PDF. Runs on Bunnahabhain
* Report Commander - command line application used to generate report PDFs by the Crystal Server (and Report Queue)
* Report Queue - python application that reads from reportqueue table to send emails and print to a printer. '''Report Queue is separate from Crystal Server, and the two systems do not interact.'''
* reportqueue - a table in the database that logs report runs.
* reportparameter - a table in the database that associates parameters to reports

== Common Errors ==

=== Error Running Report ===

This means that Report Commander encountered an error running the report. If you get this error, check the reportqueue error for a more detailed error message. Listed below are some common ones.

==== "Missing parameter values" or "Double check the parameters..."====

This means that Report Commander did not receive all required parameters for the report. Often times, the report will run fine on desktop, because the Crystal SDK can "fill in the gaps", while the web Report Viewer cannot, and needs a row in reportparameter for every parameter.

===== Solution =====

Since this is caused by missing rows in the reportparameter table, re-running the adder scripts will generally fix the issue.

If it doesn't, the adder script could be out of date or otherwise missing parameters.

==== Parameter not found in report: <parametername> ====

This means that a report was passed a parameter it doesn't expect.

===== Solution =====

Make sure the report is up to date

==== (I can't remember the error message) ====

Missing / invalid ODBC configuration. I think this presents as "could not connect to the database" or something to that effect.

===== Solution =====

Brian can make sure the ODBC connection is valid, and give Charles the name to check that the ODBC connection name in the Crystal Server config is correct.

==== Invalid Value for <parameter> ====

Report Commander received an invalid value for the specified parameter

=== Invalid Session ===

This error is caused by the Crystal Server failing to verify the session token it was passed.

==== Solution ====

Most likely, if logging out and back in doesn't fix it, this means that the Crystal Server configuration is either missing, or configured with a different database host URL than the API. Charles can check the logs to double check, as well as update the config file. Brian can then restart the Crystal Server service to load the updated configuration.

=== Invalid Report ===

The Crystal Server failed to find the report with the specified name/type. Or, the report is missing its corresponding <code>file</code> data.

=== The file or directory is corrupted and unreadable ===

Once or twice the cached .rpt file on Bunnahabhain was corrupted or something. We fixed it by reuploading the report to the customer's db and deleting the cached .rpt file from <code>\\192.168.5.18\Node\crystal-reports-server\cache</code>

It's possible it was because the D drive was failing. Cache has been moved to M:\report_cache

=== Other Errors ===

<code>Error: WARNING: MYSQL_OPT_RECONNECT is deprecated and will be removed in a future version.</code> - Disable "Auto Reconnect" on ODBC. Presents as "Unkown Error" or "Internal Server Error" in the UI

== Common Errors (Table Mode)==

{| class="wikitable" style=""
|+ Common Errors
|-
! style="min-width: 100px;"| Error !! Description !! How to Fix
|-
| Invalid Session. Try logging out and logging back in. || This means that the report server was not able to verify your session. Either your session has expired, or the Crystal Server is not configured for that database. The most likely cause of this is, if logging out and back in doesn't fix it, is that the (generally Presage) customer hasn't been set up on the Crystal Server, or some configuration has changed. || If the config for that customer is missing, then add it matching the template. If it is present, make sure that the Crystal Server and Chromium/Presage API are configured with the same DB URL. Otherwise, check the ODBC connection and DB credentials. Charles can check the logs to double check the URLs are good, as well as update the config file. Brian can then restart the Crystal Server service to load the updated configuration.
|-
| rowspan="4" |Error running report. Double check the report parameters and try again. || This means that Report Commander did not receive the correct amount of parameters for the report. Often times, the report will run fine on desktop, because the Crystal SDK can "fill in the gaps" or ignore extra parameters, while the web Report Viewer cannot, and needs a row in reportparameter for every parameter. Check the <code>Report Viewer > History</code> tab for more error details || Generally, update the report and re-run adders, but '''See Below''' for more details, and check <code>Report Viewer > History</code> for more parameter and error details. If updating the report and adder doesn't fix it, it's possible that they are out of date and need fixed.
|-
| '''"Invalid value for <parameter>"''' means Report Commander received an invalid value for the listed parameter. Usually this just means you forgot to fill a parameter out, but could be caused by by an outdated report / adders. || Make sure all parameters are filled out.
|-
| '''"Parameter not found in report: <parameter>"''' means that a parameter was passed to the report that the report doesn't expect. || If caused by an out-of-date report (more common), update the report. If caused by out-of-date adders, re-run adders.
|-
| '''"Missing parameter values"''' means that the report was not passed all expected parameters. Normally, this is because a parameter was added to the report, and the adders are out of date. || Re-run adders.
|-
|| (I can't remember the error message) || Missing / invalid ODBC configuration. I think this presents as "could not connect to the database" or something to that effect. Sometimes it'll give you a "database vendor code" just like ITrack desktop. || Depending on the error code, Brian can make sure the ODBC connection is valid, and give Charles the name to check that the ODBC connection name in the Crystal Server config is correct. But some error codes like 1064 are unrelated to the odbc setup
|-
|| Invalid Report || The Crystal Server failed to find the report with the specified name/type. || Make sure the report exists in the customer database with the given name and type, and a valid <code>report.fileid</code>. In Presage, there used to be a bug where running reports with a non-English language selected would fail with this error.
|-
|| The file or directory is corrupted and unreadable || This would come up every so often because the D drive on Bunnahabhain was failing. It shouldn't happen anymore. || It shouldn't happen again, but if it does, delete the cached report file from <code>M:\report_cache</code> on Bunnahabhain. Maybe reupload the report if it persists after that.
|-
|| <code>Database Vendor Code (code)</code> || There was some MySQL error. Look up the error code. || Might depend on the error code, but it's probably because of a bad query in the report. Reupload report.
|-
|| <code>Internal Server Error</code> || You're probably on a version of EEW that doesn't forward the error to the client properly. || Check Report Viewer > History to see the actual error
|}

== Logs ==

The log file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\crystalserverservice.log</code>

A normal log entry for a report job looks like this:

<pre>
Connection created for 'hosteddb-southeast.isoftdata.com.373487'
args [
'-report="D:\\Node\\crystal-reports-server\\cache\\A95AC82D42C7A2A9AFF9F720DA5F3159.rpt"',
'-login!={server:reporting_hosted_southeast}{database:373487}',
'-exportfile="D:\\Node\\crystal-reports-server\\cache\\output\\default_invoice_2024-12-03T19-20-25.872Z.pdf"',
'-exportformat="PDF"',
'-namedparameters invoicenum="5150"'
]
Destroying connection for 'hosteddb-southeast.isoftdata.com.373487'
</pre>

If you see a message like this, then the Crystal Server (not ODBC) failed to connect to the database, and there will probably be a logged request body right below it. The logged request body should have the db host sent from the application, which can be compared to the valid hosts in the config file

<pre>
Destroying connection for 'iceriver.presageanalytics.com.UNKNOWN DATABASE'
</pre>

The most common errors you'll see start like this and will show the command used to run Report Commander as well as a more-detailed error message in a mess of JSON.

<pre>
ReportError: A Report Commander error has occurred
</pre>

== Configuration ==

This will go over how to configure a customer on the Crystal Server, not so much how to deploy and configure a new Crystal Server.

The config file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\config.json</code>

=== Chromium ===

Does not have to be configured per-customer. One config per VM. The users have more security and so they use more of the SSL options than other users

=== Presage Web/API ===

<code>REPORT_SERVER_URI</code> specifies the report server URI used by the server, and <code>MYSQL_HOST</code> specifies the DB host. <code>EXTERNAL_DB_HOST</code> will be sent to the Crystal Server instead of <code>MYSQL_HOST</code>, if specified. '''Either <code>MYSQL_HOST</code> or <code>EXTERNAL_DB_HOST</code> MUST match the <code>host</code> in the Crystal Server config file or it will not work!'''

==== SMB ====

Currently (12/04/2024), Culligan GI is the only Presage SMB customer, and was configured individually. Maybe in the future, Presage SMB will work like Chromium and just have one config per VM, but that's not currently the case.

Since the setup for SMB clients is slightly different, the <code>MYSQL_HOST</code> is an "internal" IP, but we need an external host that matches what the Crystal Server knows. To get around this, specify this ENV variable:<code>EXTERNAL_DB_HOST: <customername>-database.presageanalytics.com</code>. Make sure the URL matches the one in the Crystal Server config. Apparently, SMB DB URLs will always have <code>-database</code> in them since the SMB docker containers don't run on the same iron as MySQL.

As of 02/03/2025, there's also Bartlett, which had some issues setting it up related to SSL. Brian fixed it, I'm not sure what he did. I think they're also set up slightly differently than Culligan GI

==== Self-Hosted ====

If they're okay hitting our Crystal Server, we just need to make sure that their database can be reached on Bunnahabhain, then the setup is the same as a hosted yard.

If not, we'll have to deploy it to a Windows server they control, and set the <code>REPORT_SERVER_URI</code> ENV variable in the API to the proper URI. Presage API will have to be able to reach <code><The Server URL>/process_report</code> in order to generate the reports

=== Enterprise Web/API ===

If we host the customer, we should just set them up on our Crystal Server. Follow the general steps for configuring them in the Crystal Server config.json, then set some ENV variables in Portainer:

* <code>REPORT_SERVER_URI: http://print.itrackchromium.com</code>
* <code>EXTERNAL_DB_HOST: example-url.itrackenterprise.com</code>

WG, UT&W, & QBT are currently (07/08/25) the only EE customers with the web report viewer on, and they also had to have the caPath set in the crystal server config to the old/not-2024 ca cert. Not sure if that'll be true for other EE customers, but it was for them.

If they're self hosted, and don't want to use our Crystal Server, follow the steps under "Deployment", then set the above ENV variables to the proper values for their setup.

== Updating ==

Not 100% sure since it's been awhile, but I'm pretty sure the process is basically:
1. Build the Crystal Server to an exe again
2. Replace the old exe on BH
3. Restart CrystalServer service

== Deployment ==

For 99% of customers, this section will not apply. But in the event that a self-hosted customer wants to host their own Crystal Server, this is probably how.

* Locate a Windows Server
* Install Report Commander on it
* Run CrystalServerSetup.exe from dl.isoftdata.com, I think this sets up the service to make it run in the background and on startup?
* Get the latest EXE or build a new one from https://github.com/ISoft-Data-Systems/crystal-reports-server and replace the old EXE from the installer
* Restart the CrystalServer service
* Make sure the service is reachable from wherever the Presage API is running
* At this point, they should be able to make a request to <code>serveruri</code>/process_report and get a report back.

== Misc / Notes ==

Housby has Crystal Server deployed to generate invoice PDFs for an ecommerce integration. They're using a version before we compiled it to an exe, so if they ever run into bugs or need an update it will be a little different

Web Report Viewer Troubleshooting

2025-06-12T18:36:24Z

Ckaup: /* Enterprise Web/API */

This article applies to Presage Web and ITrack Chromium. The web Report Viewer will give a general error, error details are logged to the reportqueue table and can be viewed in the "History" (web) or "Print Queue" (desktop) tab of the Report Viewer screen.

== Terms ==

* Crystal Server - the Node.JS application that uses Report Commander to generate the report PDF. Runs on Bunnahabhain
* Report Commander - command line application used to generate report PDFs by the Crystal Server (and Report Queue)
* Report Queue - python application that reads from reportqueue table to send emails and print to a printer. '''Report Queue is separate from Crystal Server, and the two systems do not interact.'''
* reportqueue - a table in the database that logs report runs.
* reportparameter - a table in the database that associates parameters to reports

== Common Errors ==

=== Error Running Report ===

This means that Report Commander encountered an error running the report. If you get this error, check the reportqueue error for a more detailed error message. Listed below are some common ones.

==== "Missing parameter values" or "Double check the parameters..."====

This means that Report Commander did not receive all required parameters for the report. Often times, the report will run fine on desktop, because the Crystal SDK can "fill in the gaps", while the web Report Viewer cannot, and needs a row in reportparameter for every parameter.

===== Solution =====

Since this is caused by missing rows in the reportparameter table, re-running the adder scripts will generally fix the issue.

If it doesn't, the adder script could be out of date or otherwise missing parameters.

==== Parameter not found in report: <parametername> ====

This means that a report was passed a parameter it doesn't expect.

===== Solution =====

Make sure the report is up to date

==== (I can't remember the error message) ====

Missing / invalid ODBC configuration. I think this presents as "could not connect to the database" or something to that effect.

===== Solution =====

Brian can make sure the ODBC connection is valid, and give Charles the name to check that the ODBC connection name in the Crystal Server config is correct.

==== Invalid Value for <parameter> ====

Report Commander received an invalid value for the specified parameter

=== Invalid Session ===

This error is caused by the Crystal Server failing to verify the session token it was passed.

==== Solution ====

Most likely, if logging out and back in doesn't fix it, this means that the Crystal Server configuration is either missing, or configured with a different database host URL than the API. Charles can check the logs to double check, as well as update the config file. Brian can then restart the Crystal Server service to load the updated configuration.

=== Invalid Report ===

The Crystal Server failed to find the report with the specified name/type. Or, the report is missing its corresponding <code>file</code> data.

=== The file or directory is corrupted and unreadable ===

Once or twice the cached .rpt file on Bunnahabhain was corrupted or something. We fixed it by reuploading the report to the customer's db and deleting the cached .rpt file from <code>\\192.168.5.18\Node\crystal-reports-server\cache</code>

It's possible it was because the D drive was failing. Cache has been moved to M:\report_cache

=== Other Errors ===

<code>Error: WARNING: MYSQL_OPT_RECONNECT is deprecated and will be removed in a future version.</code> - Disable "Auto Reconnect" on ODBC. Presents as "Unkown Error" or "Internal Server Error" in the UI

== Common Errors (Table Mode)==

{| class="wikitable" style=""
|+ Common Errors
|-
! style="min-width: 100px;"| Error !! Description !! How to Fix
|-
| Invalid Session. Try logging out and logging back in. || This means that the report server was not able to verify your session. Either your session has expired, or the Crystal Server is not configured for that database. The most likely cause of this is, if logging out and back in doesn't fix it, is that the (generally Presage) customer hasn't been set up on the Crystal Server, or some configuration has changed. || If the config for that customer is missing, then add it matching the template. If it is present, make sure that the Crystal Server and Chromium/Presage API are configured with the same DB URL. Otherwise, check the ODBC connection and DB credentials. Charles can check the logs to double check the URLs are good, as well as update the config file. Brian can then restart the Crystal Server service to load the updated configuration.
|-
| rowspan="4" |Error running report. Double check the report parameters and try again. || This means that Report Commander did not receive the correct amount of parameters for the report. Often times, the report will run fine on desktop, because the Crystal SDK can "fill in the gaps" or ignore extra parameters, while the web Report Viewer cannot, and needs a row in reportparameter for every parameter. Check the <code>Report Viewer > History</code> tab for more error details || Generally, update the report and re-run adders, but '''See Below''' for more details, and check <code>Report Viewer > History</code> for more parameter and error details. If updating the report and adder doesn't fix it, it's possible that they are out of date and need fixed.
|-
| '''"Invalid value for <parameter>"''' means Report Commander received an invalid value for the listed parameter. Usually this just means you forgot to fill a parameter out, but could be caused by by an outdated report / adders. || Make sure all parameters are filled out.
|-
| '''"Parameter not found in report: <parameter>"''' means that a parameter was passed to the report that the report doesn't expect. || If caused by an out-of-date report (more common), update the report. If caused by out-of-date adders, re-run adders.
|-
| '''"Missing parameter values"''' means that the report was not passed all expected parameters. Normally, this is because a parameter was added to the report, and the adders are out of date. || Re-run adders.
|-
|| (I can't remember the error message) || Missing / invalid ODBC configuration. I think this presents as "could not connect to the database" or something to that effect. Sometimes it'll give you a "database vendor code" just like ITrack desktop. || Depending on the error code, Brian can make sure the ODBC connection is valid, and give Charles the name to check that the ODBC connection name in the Crystal Server config is correct. But some error codes like 1064 are unrelated to the odbc setup
|-
|| Invalid Report || The Crystal Server failed to find the report with the specified name/type. || Make sure the report exists in the customer database with the given name and type, and a valid <code>report.fileid</code>. In Presage, there used to be a bug where running reports with a non-English language selected would fail with this error.
|-
|| The file or directory is corrupted and unreadable || This would come up every so often because the D drive on Bunnahabhain was failing. It shouldn't happen anymore. || It shouldn't happen again, but if it does, delete the cached report file from <code>M:\report_cache</code> on Bunnahabhain. Maybe reupload the report if it persists after that.
|-
|| <code>Database Vendor Code (code)</code> || There was some MySQL error. Look up the error code. || Might depend on the error code, but it's probably because of a bad query in the report. Reupload report.
|-
|| <code>Internal Server Error</code> || You're probably on a version of EEW that doesn't forward the error to the client properly. || Check Report Viewer > History to see the actual error
|}

== Logs ==

The log file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\crystalserverservice.log</code>

A normal log entry for a report job looks like this:

<pre>
Connection created for 'hosteddb-southeast.isoftdata.com.373487'
args [
'-report="D:\\Node\\crystal-reports-server\\cache\\A95AC82D42C7A2A9AFF9F720DA5F3159.rpt"',
'-login!={server:reporting_hosted_southeast}{database:373487}',
'-exportfile="D:\\Node\\crystal-reports-server\\cache\\output\\default_invoice_2024-12-03T19-20-25.872Z.pdf"',
'-exportformat="PDF"',
'-namedparameters invoicenum="5150"'
]
Destroying connection for 'hosteddb-southeast.isoftdata.com.373487'
</pre>

If you see a message like this, then the Crystal Server (not ODBC) failed to connect to the database, and there will probably be a logged request body right below it. The logged request body should have the db host sent from the application, which can be compared to the valid hosts in the config file

<pre>
Destroying connection for 'iceriver.presageanalytics.com.UNKNOWN DATABASE'
</pre>

The most common errors you'll see start like this and will show the command used to run Report Commander as well as a more-detailed error message in a mess of JSON.

<pre>
ReportError: A Report Commander error has occurred
</pre>

== Configuration ==

This will go over how to configure a customer on the Crystal Server, not so much how to deploy and configure a new Crystal Server.

The config file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\config.json</code>

=== Chromium ===

Does not have to be configured per-customer. One config per VM. The users have more security and so they use more of the SSL options than other users

=== Presage Web/API ===

<code>REPORT_SERVER_URI</code> specifies the report server URI used by the server, and <code>MYSQL_HOST</code> specifies the DB host. <code>EXTERNAL_DB_HOST</code> will be sent to the Crystal Server instead of <code>MYSQL_HOST</code>, if specified. '''Either <code>MYSQL_HOST</code> or <code>EXTERNAL_DB_HOST</code> MUST match the <code>host</code> in the Crystal Server config file or it will not work!'''

==== SMB ====

Currently (12/04/2024), Culligan GI is the only Presage SMB customer, and was configured individually. Maybe in the future, Presage SMB will work like Chromium and just have one config per VM, but that's not currently the case.

Since the setup for SMB clients is slightly different, the <code>MYSQL_HOST</code> is an "internal" IP, but we need an external host that matches what the Crystal Server knows. To get around this, specify this ENV variable:<code>EXTERNAL_DB_HOST: <customername>-database.presageanalytics.com</code>. Make sure the URL matches the one in the Crystal Server config. Apparently, SMB DB URLs will always have <code>-database</code> in them since the SMB docker containers don't run on the same iron as MySQL.

As of 02/03/2025, there's also Bartlett, which had some issues setting it up related to SSL. Brian fixed it, I'm not sure what he did. I think they're also set up slightly differently than Culligan GI

==== Self-Hosted ====

If they're okay hitting our Crystal Server, we just need to make sure that their database can be reached on Bunnahabhain, then the setup is the same as a hosted yard.

If not, we'll have to deploy it to a Windows server they control, and set the <code>REPORT_SERVER_URI</code> ENV variable in the API to the proper URI. Presage API will have to be able to reach <code><The Server URL>/process_report</code> in order to generate the reports

=== Enterprise Web/API ===

If we host the customer, we should just set them up on our Crystal Server. Follow the general steps for configuring them in the Crystal Server config.json, then set some ENV variables in Portainer:

* <code>REPORT_SERVER_URI: http://print.itrackchromium.com</code>
* <code>EXTERNAL_DB_HOST: example-url.itrackenterprise.com</code>

WG and UT&W are currently (6/12/25) the only EE customers with the web report viewer on, and they also had to have the caPath set in the crystal server config to the old/not-2024 ca cert. Not sure if that'll be true for other EE customers, but it was for them.

If they're self hosted, and don't want to use our Crystal Server, follow the steps under "Deployment", then set the above ENV variables to the proper values for their setup.

== Updating ==

Not 100% sure since it's been awhile, but I'm pretty sure the process is basically:
1. Build the Crystal Server to an exe again
2. Replace the old exe on BH
3. Restart CrystalServer service

== Deployment ==

For 99% of customers, this section will not apply. But in the event that a self-hosted customer wants to host their own Crystal Server, this is probably how.

* Locate a Windows Server
* Install Report Commander on it
* Run CrystalServerSetup.exe from dl.isoftdata.com, I think this sets up the service to make it run in the background and on startup?
* Get the latest EXE or build a new one from https://github.com/ISoft-Data-Systems/crystal-reports-server and replace the old EXE from the installer
* Restart the CrystalServer service
* Make sure the service is reachable from wherever the Presage API is running
* At this point, they should be able to make a request to <code>serveruri</code>/process_report and get a report back.

== Misc / Notes ==

Housby has Crystal Server deployed to generate invoice PDFs for an ecommerce integration. They're using a version before we compiled it to an exe, so if they ever run into bugs or need an update it will be a little different

Web Report Viewer Troubleshooting

2025-06-12T18:35:05Z

Ckaup: /* Common Errors (Table Mode) */

This article applies to Presage Web and ITrack Chromium. The web Report Viewer will give a general error, error details are logged to the reportqueue table and can be viewed in the "History" (web) or "Print Queue" (desktop) tab of the Report Viewer screen.

== Terms ==

* Crystal Server - the Node.JS application that uses Report Commander to generate the report PDF. Runs on Bunnahabhain
* Report Commander - command line application used to generate report PDFs by the Crystal Server (and Report Queue)
* Report Queue - python application that reads from reportqueue table to send emails and print to a printer. '''Report Queue is separate from Crystal Server, and the two systems do not interact.'''
* reportqueue - a table in the database that logs report runs.
* reportparameter - a table in the database that associates parameters to reports

== Common Errors ==

=== Error Running Report ===

This means that Report Commander encountered an error running the report. If you get this error, check the reportqueue error for a more detailed error message. Listed below are some common ones.

==== "Missing parameter values" or "Double check the parameters..."====

This means that Report Commander did not receive all required parameters for the report. Often times, the report will run fine on desktop, because the Crystal SDK can "fill in the gaps", while the web Report Viewer cannot, and needs a row in reportparameter for every parameter.

===== Solution =====

Since this is caused by missing rows in the reportparameter table, re-running the adder scripts will generally fix the issue.

If it doesn't, the adder script could be out of date or otherwise missing parameters.

==== Parameter not found in report: <parametername> ====

This means that a report was passed a parameter it doesn't expect.

===== Solution =====

Make sure the report is up to date

==== (I can't remember the error message) ====

Missing / invalid ODBC configuration. I think this presents as "could not connect to the database" or something to that effect.

===== Solution =====

Brian can make sure the ODBC connection is valid, and give Charles the name to check that the ODBC connection name in the Crystal Server config is correct.

==== Invalid Value for <parameter> ====

Report Commander received an invalid value for the specified parameter

=== Invalid Session ===

This error is caused by the Crystal Server failing to verify the session token it was passed.

==== Solution ====

Most likely, if logging out and back in doesn't fix it, this means that the Crystal Server configuration is either missing, or configured with a different database host URL than the API. Charles can check the logs to double check, as well as update the config file. Brian can then restart the Crystal Server service to load the updated configuration.

=== Invalid Report ===

The Crystal Server failed to find the report with the specified name/type. Or, the report is missing its corresponding <code>file</code> data.

=== The file or directory is corrupted and unreadable ===

Once or twice the cached .rpt file on Bunnahabhain was corrupted or something. We fixed it by reuploading the report to the customer's db and deleting the cached .rpt file from <code>\\192.168.5.18\Node\crystal-reports-server\cache</code>

It's possible it was because the D drive was failing. Cache has been moved to M:\report_cache

=== Other Errors ===

<code>Error: WARNING: MYSQL_OPT_RECONNECT is deprecated and will be removed in a future version.</code> - Disable "Auto Reconnect" on ODBC. Presents as "Unkown Error" or "Internal Server Error" in the UI

== Common Errors (Table Mode)==

{| class="wikitable" style=""
|+ Common Errors
|-
! style="min-width: 100px;"| Error !! Description !! How to Fix
|-
| Invalid Session. Try logging out and logging back in. || This means that the report server was not able to verify your session. Either your session has expired, or the Crystal Server is not configured for that database. The most likely cause of this is, if logging out and back in doesn't fix it, is that the (generally Presage) customer hasn't been set up on the Crystal Server, or some configuration has changed. || If the config for that customer is missing, then add it matching the template. If it is present, make sure that the Crystal Server and Chromium/Presage API are configured with the same DB URL. Otherwise, check the ODBC connection and DB credentials. Charles can check the logs to double check the URLs are good, as well as update the config file. Brian can then restart the Crystal Server service to load the updated configuration.
|-
| rowspan="4" |Error running report. Double check the report parameters and try again. || This means that Report Commander did not receive the correct amount of parameters for the report. Often times, the report will run fine on desktop, because the Crystal SDK can "fill in the gaps" or ignore extra parameters, while the web Report Viewer cannot, and needs a row in reportparameter for every parameter. Check the <code>Report Viewer > History</code> tab for more error details || Generally, update the report and re-run adders, but '''See Below''' for more details, and check <code>Report Viewer > History</code> for more parameter and error details. If updating the report and adder doesn't fix it, it's possible that they are out of date and need fixed.
|-
| '''"Invalid value for <parameter>"''' means Report Commander received an invalid value for the listed parameter. Usually this just means you forgot to fill a parameter out, but could be caused by by an outdated report / adders. || Make sure all parameters are filled out.
|-
| '''"Parameter not found in report: <parameter>"''' means that a parameter was passed to the report that the report doesn't expect. || If caused by an out-of-date report (more common), update the report. If caused by out-of-date adders, re-run adders.
|-
| '''"Missing parameter values"''' means that the report was not passed all expected parameters. Normally, this is because a parameter was added to the report, and the adders are out of date. || Re-run adders.
|-
|| (I can't remember the error message) || Missing / invalid ODBC configuration. I think this presents as "could not connect to the database" or something to that effect. Sometimes it'll give you a "database vendor code" just like ITrack desktop. || Depending on the error code, Brian can make sure the ODBC connection is valid, and give Charles the name to check that the ODBC connection name in the Crystal Server config is correct. But some error codes like 1064 are unrelated to the odbc setup
|-
|| Invalid Report || The Crystal Server failed to find the report with the specified name/type. || Make sure the report exists in the customer database with the given name and type, and a valid <code>report.fileid</code>. In Presage, there used to be a bug where running reports with a non-English language selected would fail with this error.
|-
|| The file or directory is corrupted and unreadable || This would come up every so often because the D drive on Bunnahabhain was failing. It shouldn't happen anymore. || It shouldn't happen again, but if it does, delete the cached report file from <code>M:\report_cache</code> on Bunnahabhain. Maybe reupload the report if it persists after that.
|-
|| <code>Database Vendor Code (code)</code> || There was some MySQL error. Look up the error code. || Might depend on the error code, but it's probably because of a bad query in the report. Reupload report.
|-
|| <code>Internal Server Error</code> || You're probably on a version of EEW that doesn't forward the error to the client properly. || Check Report Viewer > History to see the actual error
|}

== Logs ==

The log file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\crystalserverservice.log</code>

A normal log entry for a report job looks like this:

<pre>
Connection created for 'hosteddb-southeast.isoftdata.com.373487'
args [
'-report="D:\\Node\\crystal-reports-server\\cache\\A95AC82D42C7A2A9AFF9F720DA5F3159.rpt"',
'-login!={server:reporting_hosted_southeast}{database:373487}',
'-exportfile="D:\\Node\\crystal-reports-server\\cache\\output\\default_invoice_2024-12-03T19-20-25.872Z.pdf"',
'-exportformat="PDF"',
'-namedparameters invoicenum="5150"'
]
Destroying connection for 'hosteddb-southeast.isoftdata.com.373487'
</pre>

If you see a message like this, then the Crystal Server (not ODBC) failed to connect to the database, and there will probably be a logged request body right below it. The logged request body should have the db host sent from the application, which can be compared to the valid hosts in the config file

<pre>
Destroying connection for 'iceriver.presageanalytics.com.UNKNOWN DATABASE'
</pre>

The most common errors you'll see start like this and will show the command used to run Report Commander as well as a more-detailed error message in a mess of JSON.

<pre>
ReportError: A Report Commander error has occurred
</pre>

== Configuration ==

This will go over how to configure a customer on the Crystal Server, not so much how to deploy and configure a new Crystal Server.

The config file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\config.json</code>

=== Chromium ===

Does not have to be configured per-customer. One config per VM. The users have more security and so they use more of the SSL options than other users

=== Presage Web/API ===

<code>REPORT_SERVER_URI</code> specifies the report server URI used by the server, and <code>MYSQL_HOST</code> specifies the DB host. <code>EXTERNAL_DB_HOST</code> will be sent to the Crystal Server instead of <code>MYSQL_HOST</code>, if specified. '''Either <code>MYSQL_HOST</code> or <code>EXTERNAL_DB_HOST</code> MUST match the <code>host</code> in the Crystal Server config file or it will not work!'''

==== SMB ====

Currently (12/04/2024), Culligan GI is the only Presage SMB customer, and was configured individually. Maybe in the future, Presage SMB will work like Chromium and just have one config per VM, but that's not currently the case.

Since the setup for SMB clients is slightly different, the <code>MYSQL_HOST</code> is an "internal" IP, but we need an external host that matches what the Crystal Server knows. To get around this, specify this ENV variable:<code>EXTERNAL_DB_HOST: <customername>-database.presageanalytics.com</code>. Make sure the URL matches the one in the Crystal Server config. Apparently, SMB DB URLs will always have <code>-database</code> in them since the SMB docker containers don't run on the same iron as MySQL.

As of 02/03/2025, there's also Bartlett, which had some issues setting it up related to SSL. Brian fixed it, I'm not sure what he did. I think they're also set up slightly differently than Culligan GI

==== Self-Hosted ====

If they're okay hitting our Crystal Server, we just need to make sure that their database can be reached on Bunnahabhain, then the setup is the same as a hosted yard.

If not, we'll have to deploy it to a Windows server they control, and set the <code>REPORT_SERVER_URI</code> ENV variable in the API to the proper URI. Presage API will have to be able to reach <code><The Server URL>/process_report</code> in order to generate the reports

=== Enterprise Web/API ===

If we host the customer, we should just set them up on our Crystal Server. Follow the general steps for configuring them in the Crystal Server config.json, then set some ENV variables in Portainer:

* <code>REPORT_SERVER_URI: http://print.itrackchromium.com</code>
* <code>EXTERNAL_DB_HOST: example-url.itrackenterprise.com</code>

WG is currently (3/11/25) the only EE customer with the web report viewer on, and they also had to have the caPath set in the crystal server config to the old/not-2024 ca cert. Not sure if that'll be true for other EE customers, but it was for them.

If they're self hosted, and don't want to use our Crystal Server, follow the steps under "Deployment", then set the above ENV variables to the proper values for their setup.

== Updating ==

Not 100% sure since it's been awhile, but I'm pretty sure the process is basically:
1. Build the Crystal Server to an exe again
2. Replace the old exe on BH
3. Restart CrystalServer service

== Deployment ==

For 99% of customers, this section will not apply. But in the event that a self-hosted customer wants to host their own Crystal Server, this is probably how.

* Locate a Windows Server
* Install Report Commander on it
* Run CrystalServerSetup.exe from dl.isoftdata.com, I think this sets up the service to make it run in the background and on startup?
* Get the latest EXE or build a new one from https://github.com/ISoft-Data-Systems/crystal-reports-server and replace the old EXE from the installer
* Restart the CrystalServer service
* Make sure the service is reachable from wherever the Presage API is running
* At this point, they should be able to make a request to <code>serveruri</code>/process_report and get a report back.

== Misc / Notes ==

Housby has Crystal Server deployed to generate invoice PDFs for an ecommerce integration. They're using a version before we compiled it to an exe, so if they ever run into bugs or need an update it will be a little different

Configuring a barcode scanner

2025-06-06T17:29:28Z

Ckaup: /* Windows 11 Industrial Rugged Tablet */

=Zebra DS2278=

This page will cover how to setup a Zebra DS2278 Bluetooth Barcode Scanner to work with iSoft products on mobile devices.

==Scanner Info==
* Approx Cost: $190-$280 depending on accessories and support
* Important Features: Bluetooth, 14 hour+ battery life, 5ft drop, 36 month warranty, 123Scan app, SDKs for iOS, Android, Windows

==Quick Start Guide==
===Android using Chrome===
* The fastest way to get started is to scan the appropriate barcode for your device type. **Make sure your device is fully charged!
* This model of scanner can scan from a high resolution monitor or screen
* Each of the barcodes below will change the defaults on your scanner. You will need to "forget" or "remove" the device in your Bluetooth settings and reconnect
* The below barcodes have the following settings: '''Prefix : Suffix $''', HID features for iOS, Host: HID BT Classic
[[Image:AndroidBarcode.JPG]]

===iOS using ITrack LX App===
'''Tip: You do not need to set up this device as a keyboard wedge'''

1. You first need to install the Zebra iOS app https://apps.apple.com/us/app/zebra-scanner-control/id1034012069

2. Open that app and go to Connection Help > Pair DS2278

[[Image:Zebra-DS2278-setup-barcodes.PNG|400px]]

3. Follow the onscreen instructions

4. Go back to the main screen and choose Connect

5. Tap on the DS2278 and choose Disconnect(this will disconnect it from the Zebra app so we can connect it to the ITrack LX app)

[[Image:Zebra-DS2278-disconnect-screen.PNG|400px]]

6. Go to the ITrack LX app and after a few seconds you should hear a connection beep from the scanner. Scanning in the ITrack LX app with the DS2278 should now work.

==Charging the Scanner==
* The charging circuit on the scanner is capable of using as much current as possible based on the power source
* Preferred Method: use a BC1.2 Compliant Micro USB adapter to a wall outlet (higher current charging capability above 900 mA)

[[Image:Zebra_battery.JPG]]

==123Scan Software==

==Explanation of Settings==

==External Links==
* Zebra Support Page [https://www.zebra.com/us/en/support-downloads/scanners/general-purpose-scanners/ds2200-series.html link]
* 123Scan Software Download [https://www.zebra.com/us/en/products/software/scanning-systems/123scan.html link]
* Full Manual Download [https://www.zebra.com/content/dam/zebra_new_ia/en-us/manuals/barcode-scanners/ds2278-prg-en.pdf link]

=Honeywell=

== Compatibility Notes ==
Please update the Chrome browser on the Honeywell to Chrome v101 so that the Teardown app is sized correctly. It currently ships with Chrome v70. -JW 2022-05-18

== Setting up a Honeywell Scanner ==
ScanPal EDA71
https://www.honeywellaidc.com/products/computer-devices/tablet/scanpaleda71

These are the screens you set through to set up the honeywell device

Settings -> Honeywell Settings -> Scan Settings -> Internal Scanner -> Default profile -> Data Processing Settings

Wedge = checked

Wedge Method = Keyboard

no Prefix

no Suffix

Wedge as keys = empty input

[[File:Flowchart_of_settings.jpg|800px|thumb|center|Honeywell Setting Flowchart]]

 

== Enterprise LX Honeywell config info ==

A global database setting "Scanner Mode (ambleMode,honeywell)" needs to be set to "honeywell"

The current default is ambleMode which may change in the near future.
The following query will let you check on the setting. Note: A user has to have logged into an lx app before the default settings are present.

<syntaxhighlight lang="sql">
SELECT
`globalsettingvalue`.`settingid`
, `setting`.`location`
, `setting`.`name`
, `globalsettingvalue`.`value`
, `setting`.`defaultvalue`
, `setting`.`scope`
, `setting`.`settingtype`
, `value`=`defaultvalue` AS isdefault
FROM
`globalsettingvalue`
INNER JOIN `setting`
ON (`globalsettingvalue`.`settingid` = `setting`.`settingid`)
WHERE (`setting`.`name` = 'Scanner Mode (ambleMode,honeywell)');
</syntaxhighlight>

=Munbyn=

== Setting up a Munbyn Scanner ==
This is for the MUNBYN IPDA081/IPDA086 Mobile Data Terminal: https://pos.munbyn.com/munbyn-ipda081-rfid-handheld-computer/ 
To set up: 
 
Swipe up to see apps, then tap on "keyboardemulator". 
On the "Function" page, make sure "Enable Scanner" is on. 
[[File:scanner1.png|200px]]
 
 
On the "AppSettings" page, turn on "Release key off scan" (if it is not already enabled).
 
[[File:scanner2.png|200px]]
 
 
Then scroll down to "Process mode". Make sure it is set to "keyboard input". Under "End mark", none of the options should be checked. 
[[File:scanner3.png|200px]]
 
 
Prefix/preamble and suffix/postamble for the device can be edited under "Data Format". If using a test program that uses prefix/suffix, be sure that the prefix/suffix in the program and in the scanner setting app (keyboardemulator) are the same. 
[[File:scanner4.png|200px]]

 

= Tera Scanner =
[[File:Tera_config.png|200px]]

To enable the trigger on the Tera scanner handle:

1. Get to the Scanner Config Page.

2. Disable the scanner.

3. Key in 293 on the scanner keypad.

4. Re-enable the scanner.

5. The scanner config page should look like the image above if it's set correctly.

== Windows 11 Industrial Rugged Tablet ==
Two additional applications are required to use the scanner features: Honeywell Download manager tool (which will manage any subsequent Honeywell software downloads), then an EZConfig for Scanning software for the configuration of scanner itself. Both parts can be downloaded from the same portal: https://hsmftp.honeywell.com/

To download the zip file containing the Honeywell Download manager tool, select "here" marked by the first arrow. When finished, right-click the zip file selecting "Extract all..." then select a home/path for this installer.

To download the EZConfig for Scanning, in the file system on the left: Software -> Barcode Scanner -> Software -> Tools and Utilities -> EZConfig for Scanning -> Current.

# Open the EZConfig for Scanning software when it's finished downloading.
# Open the file "EZConfig-Scanning v4_msedge"
# select "Connected Device"
# select "Configure Device"
# select "Data Formatting"
# in Data Formatting, verify that you are on the "Prefix/Suffix" tab
# enter <code>~</code> as the Prefix
# enter <code>{ CR}</code> as the Suffix

== NOTE on ENTERPRISE LX setup ==
enterpise lx default pre/postable
preamble = "126" = "~"
postamble = "13" = "Enter"

For munbyn scanner, the postamble/suffix does not allow you to use "Enter" so you need to leave that blank and instead check the box under EndMark that says "Enter"

Web Report Viewer Troubleshooting

2025-06-04T19:27:43Z

Ckaup: /* Common Errors (Table Mode) */

This article applies to Presage Web and ITrack Chromium. The web Report Viewer will give a general error, error details are logged to the reportqueue table and can be viewed in the "History" (web) or "Print Queue" (desktop) tab of the Report Viewer screen.

== Terms ==

* Crystal Server - the Node.JS application that uses Report Commander to generate the report PDF. Runs on Bunnahabhain
* Report Commander - command line application used to generate report PDFs by the Crystal Server (and Report Queue)
* Report Queue - python application that reads from reportqueue table to send emails and print to a printer. '''Report Queue is separate from Crystal Server, and the two systems do not interact.'''
* reportqueue - a table in the database that logs report runs.
* reportparameter - a table in the database that associates parameters to reports

== Common Errors ==

=== Error Running Report ===

This means that Report Commander encountered an error running the report. If you get this error, check the reportqueue error for a more detailed error message. Listed below are some common ones.

==== "Missing parameter values" or "Double check the parameters..."====

This means that Report Commander did not receive all required parameters for the report. Often times, the report will run fine on desktop, because the Crystal SDK can "fill in the gaps", while the web Report Viewer cannot, and needs a row in reportparameter for every parameter.

===== Solution =====

Since this is caused by missing rows in the reportparameter table, re-running the adder scripts will generally fix the issue.

If it doesn't, the adder script could be out of date or otherwise missing parameters.

==== Parameter not found in report: <parametername> ====

This means that a report was passed a parameter it doesn't expect.

===== Solution =====

Make sure the report is up to date

==== (I can't remember the error message) ====

Missing / invalid ODBC configuration. I think this presents as "could not connect to the database" or something to that effect.

===== Solution =====

Brian can make sure the ODBC connection is valid, and give Charles the name to check that the ODBC connection name in the Crystal Server config is correct.

==== Invalid Value for <parameter> ====

Report Commander received an invalid value for the specified parameter

=== Invalid Session ===

This error is caused by the Crystal Server failing to verify the session token it was passed.

==== Solution ====

Most likely, if logging out and back in doesn't fix it, this means that the Crystal Server configuration is either missing, or configured with a different database host URL than the API. Charles can check the logs to double check, as well as update the config file. Brian can then restart the Crystal Server service to load the updated configuration.

=== Invalid Report ===

The Crystal Server failed to find the report with the specified name/type. Or, the report is missing its corresponding <code>file</code> data.

=== The file or directory is corrupted and unreadable ===

Once or twice the cached .rpt file on Bunnahabhain was corrupted or something. We fixed it by reuploading the report to the customer's db and deleting the cached .rpt file from <code>\\192.168.5.18\Node\crystal-reports-server\cache</code>

It's possible it was because the D drive was failing. Cache has been moved to M:\report_cache

=== Other Errors ===

<code>Error: WARNING: MYSQL_OPT_RECONNECT is deprecated and will be removed in a future version.</code> - Disable "Auto Reconnect" on ODBC. Presents as "Unkown Error" or "Internal Server Error" in the UI

== Common Errors (Table Mode)==

{| class="wikitable" style=""
|+ Common Errors
|-
! style="min-width: 100px;"| Error !! Description !! How to Fix
|-
| Invalid Session. Try logging out and logging back in. || This means that the report server was not able to verify your session. Either your session has expired, or the Crystal Server is not configured for that database. The most likely cause of this is, if logging out and back in doesn't fix it, is that the (generally Presage) customer hasn't been set up on the Crystal Server, or some configuration has changed. || If the config for that customer is missing, then add it matching the template. If it is present, make sure that the Crystal Server and Chromium/Presage API are configured with the same DB URL. Otherwise, check the ODBC connection and DB credentials. Charles can check the logs to double check the URLs are good, as well as update the config file. Brian can then restart the Crystal Server service to load the updated configuration.
|-
| rowspan="4" |Error running report. Double check the report parameters and try again. || This means that Report Commander did not receive the correct amount of parameters for the report. Often times, the report will run fine on desktop, because the Crystal SDK can "fill in the gaps" or ignore extra parameters, while the web Report Viewer cannot, and needs a row in reportparameter for every parameter. Check the <code>Report Viewer > History</code> tab for more error details || Generally, update the report and re-run adders, but '''See Below''' for more details, and check <code>Report Viewer > History</code> for more parameter and error details. If updating the report and adder doesn't fix it, it's possible that they are out of date and need fixed.
|-
| '''"Invalid value for <parameter>"''' means Report Commander received an invalid value for the listed parameter. Usually this just means you forgot to fill a parameter out, but could be caused by by an outdated report / adders. || Make sure all parameters are filled out.
|-
| '''"Parameter not found in report: <parameter>"''' means that a parameter was passed to the report that the report doesn't expect. || If caused by an out-of-date report (more common), update the report. If caused by out-of-date adders, re-run adders.
|-
| '''"Missing parameter values"''' means that the report was not passed all expected parameters. Normally, this is because a parameter was added to the report, and the adders are out of date. || Re-run adders.
|-
|| (I can't remember the error message) || Missing / invalid ODBC configuration. I think this presents as "could not connect to the database" or something to that effect. Sometimes it'll give you a "database vendor code" just like ITrack desktop. || Depending on the error code, Brian can make sure the ODBC connection is valid, and give Charles the name to check that the ODBC connection name in the Crystal Server config is correct. But some error codes like 1064 are unrelated to the odbc setup
|-
|| Invalid Report || The Crystal Server failed to find the report with the specified name/type. || Make sure the report exists in the customer database with the given name and type, and a valid <code>report.fileid</code>. In Presage, there used to be a bug where running reports with a non-English language selected would fail with this error.
|-
|| The file or directory is corrupted and unreadable || This would come up every so often because the D drive on Bunnahabhain was failing. It shouldn't happen anymore. || It shouldn't happen again, but if it does, delete the cached report file from <code>M:\report_cache</code> on Bunnahabhain. Maybe reupload the report if it persists after that.
|-
|| <code>Database Vendor Code (code)</code> || There was some MySQL error. Look up the error code. || Might depend on the error code, but it's probably because of a bad query in the report. Reupload report.
|}

== Logs ==

The log file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\crystalserverservice.log</code>

A normal log entry for a report job looks like this:

<pre>
Connection created for 'hosteddb-southeast.isoftdata.com.373487'
args [
'-report="D:\\Node\\crystal-reports-server\\cache\\A95AC82D42C7A2A9AFF9F720DA5F3159.rpt"',
'-login!={server:reporting_hosted_southeast}{database:373487}',
'-exportfile="D:\\Node\\crystal-reports-server\\cache\\output\\default_invoice_2024-12-03T19-20-25.872Z.pdf"',
'-exportformat="PDF"',
'-namedparameters invoicenum="5150"'
]
Destroying connection for 'hosteddb-southeast.isoftdata.com.373487'
</pre>

If you see a message like this, then the Crystal Server (not ODBC) failed to connect to the database, and there will probably be a logged request body right below it. The logged request body should have the db host sent from the application, which can be compared to the valid hosts in the config file

<pre>
Destroying connection for 'iceriver.presageanalytics.com.UNKNOWN DATABASE'
</pre>

The most common errors you'll see start like this and will show the command used to run Report Commander as well as a more-detailed error message in a mess of JSON.

<pre>
ReportError: A Report Commander error has occurred
</pre>

== Configuration ==

This will go over how to configure a customer on the Crystal Server, not so much how to deploy and configure a new Crystal Server.

The config file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\config.json</code>

=== Chromium ===

Does not have to be configured per-customer. One config per VM. The users have more security and so they use more of the SSL options than other users

=== Presage Web/API ===

<code>REPORT_SERVER_URI</code> specifies the report server URI used by the server, and <code>MYSQL_HOST</code> specifies the DB host. <code>EXTERNAL_DB_HOST</code> will be sent to the Crystal Server instead of <code>MYSQL_HOST</code>, if specified. '''Either <code>MYSQL_HOST</code> or <code>EXTERNAL_DB_HOST</code> MUST match the <code>host</code> in the Crystal Server config file or it will not work!'''

==== SMB ====

Currently (12/04/2024), Culligan GI is the only Presage SMB customer, and was configured individually. Maybe in the future, Presage SMB will work like Chromium and just have one config per VM, but that's not currently the case.

Since the setup for SMB clients is slightly different, the <code>MYSQL_HOST</code> is an "internal" IP, but we need an external host that matches what the Crystal Server knows. To get around this, specify this ENV variable:<code>EXTERNAL_DB_HOST: <customername>-database.presageanalytics.com</code>. Make sure the URL matches the one in the Crystal Server config. Apparently, SMB DB URLs will always have <code>-database</code> in them since the SMB docker containers don't run on the same iron as MySQL.

As of 02/03/2025, there's also Bartlett, which had some issues setting it up related to SSL. Brian fixed it, I'm not sure what he did. I think they're also set up slightly differently than Culligan GI

==== Self-Hosted ====

If they're okay hitting our Crystal Server, we just need to make sure that their database can be reached on Bunnahabhain, then the setup is the same as a hosted yard.

If not, we'll have to deploy it to a Windows server they control, and set the <code>REPORT_SERVER_URI</code> ENV variable in the API to the proper URI. Presage API will have to be able to reach <code><The Server URL>/process_report</code> in order to generate the reports

=== Enterprise Web/API ===

If we host the customer, we should just set them up on our Crystal Server. Follow the general steps for configuring them in the Crystal Server config.json, then set some ENV variables in Portainer:

* <code>REPORT_SERVER_URI: http://print.itrackchromium.com</code>
* <code>EXTERNAL_DB_HOST: example-url.itrackenterprise.com</code>

WG is currently (3/11/25) the only EE customer with the web report viewer on, and they also had to have the caPath set in the crystal server config to the old/not-2024 ca cert. Not sure if that'll be true for other EE customers, but it was for them.

If they're self hosted, and don't want to use our Crystal Server, follow the steps under "Deployment", then set the above ENV variables to the proper values for their setup.

== Updating ==

Not 100% sure since it's been awhile, but I'm pretty sure the process is basically:
1. Build the Crystal Server to an exe again
2. Replace the old exe on BH
3. Restart CrystalServer service

== Deployment ==

For 99% of customers, this section will not apply. But in the event that a self-hosted customer wants to host their own Crystal Server, this is probably how.

* Locate a Windows Server
* Install Report Commander on it
* Run CrystalServerSetup.exe from dl.isoftdata.com, I think this sets up the service to make it run in the background and on startup?
* Get the latest EXE or build a new one from https://github.com/ISoft-Data-Systems/crystal-reports-server and replace the old EXE from the installer
* Restart the CrystalServer service
* Make sure the service is reachable from wherever the Presage API is running
* At this point, they should be able to make a request to <code>serveruri</code>/process_report and get a report back.

== Misc / Notes ==

Housby has Crystal Server deployed to generate invoice PDFs for an ecommerce integration. They're using a version before we compiled it to an exe, so if they ever run into bugs or need an update it will be a little different

Web Report Viewer Troubleshooting

2025-06-04T19:27:16Z

Ckaup:

This article applies to Presage Web and ITrack Chromium. The web Report Viewer will give a general error, error details are logged to the reportqueue table and can be viewed in the "History" (web) or "Print Queue" (desktop) tab of the Report Viewer screen.

== Terms ==

* Crystal Server - the Node.JS application that uses Report Commander to generate the report PDF. Runs on Bunnahabhain
* Report Commander - command line application used to generate report PDFs by the Crystal Server (and Report Queue)
* Report Queue - python application that reads from reportqueue table to send emails and print to a printer. '''Report Queue is separate from Crystal Server, and the two systems do not interact.'''
* reportqueue - a table in the database that logs report runs.
* reportparameter - a table in the database that associates parameters to reports

== Common Errors ==

=== Error Running Report ===

This means that Report Commander encountered an error running the report. If you get this error, check the reportqueue error for a more detailed error message. Listed below are some common ones.

==== "Missing parameter values" or "Double check the parameters..."====

This means that Report Commander did not receive all required parameters for the report. Often times, the report will run fine on desktop, because the Crystal SDK can "fill in the gaps", while the web Report Viewer cannot, and needs a row in reportparameter for every parameter.

===== Solution =====

Since this is caused by missing rows in the reportparameter table, re-running the adder scripts will generally fix the issue.

If it doesn't, the adder script could be out of date or otherwise missing parameters.

==== Parameter not found in report: <parametername> ====

This means that a report was passed a parameter it doesn't expect.

===== Solution =====

Make sure the report is up to date

==== (I can't remember the error message) ====

Missing / invalid ODBC configuration. I think this presents as "could not connect to the database" or something to that effect.

===== Solution =====

Brian can make sure the ODBC connection is valid, and give Charles the name to check that the ODBC connection name in the Crystal Server config is correct.

==== Invalid Value for <parameter> ====

Report Commander received an invalid value for the specified parameter

=== Invalid Session ===

This error is caused by the Crystal Server failing to verify the session token it was passed.

==== Solution ====

Most likely, if logging out and back in doesn't fix it, this means that the Crystal Server configuration is either missing, or configured with a different database host URL than the API. Charles can check the logs to double check, as well as update the config file. Brian can then restart the Crystal Server service to load the updated configuration.

=== Invalid Report ===

The Crystal Server failed to find the report with the specified name/type. Or, the report is missing its corresponding <code>file</code> data.

=== The file or directory is corrupted and unreadable ===

Once or twice the cached .rpt file on Bunnahabhain was corrupted or something. We fixed it by reuploading the report to the customer's db and deleting the cached .rpt file from <code>\\192.168.5.18\Node\crystal-reports-server\cache</code>

It's possible it was because the D drive was failing. Cache has been moved to M:\report_cache

=== Other Errors ===

<code>Error: WARNING: MYSQL_OPT_RECONNECT is deprecated and will be removed in a future version.</code> - Disable "Auto Reconnect" on ODBC. Presents as "Unkown Error" or "Internal Server Error" in the UI

== Common Errors (Table Mode)==

{| class="wikitable" style=""
|+ Common Errors
|-
! style="min-width: 100px;"| Error !! Description !! How to Fix
|-
| Invalid Session. Try logging out and logging back in. || This means that the report server was not able to verify your session. Either your session has expired, or the Crystal Server is not configured for that database. The most likely cause of this is, if logging out and back in doesn't fix it, is that the (generally Presage) customer hasn't been set up on the Crystal Server, or some configuration has changed. || If the config for that customer is missing, then add it matching the template. If it is present, make sure that the Crystal Server and Chromium/Presage API are configured with the same DB URL. Otherwise, check the ODBC connection and DB credentials. Charles can check the logs to double check the URLs are good, as well as update the config file. Brian can then restart the Crystal Server service to load the updated configuration.
|-
| rowspan="4" |Error running report. Double check the report parameters and try again. || This means that Report Commander did not receive the correct amount of parameters for the report. Often times, the report will run fine on desktop, because the Crystal SDK can "fill in the gaps" or ignore extra parameters, while the web Report Viewer cannot, and needs a row in reportparameter for every parameter. Check the <code>Report Viewer > History</code> tab for more error details || Generally, update the report and re-run adders, but '''See Below''' for more details, and check <code>Report Viewer > History</code> for more parameter and error details. If updating the report and adder doesn't fix it, it's possible that they are out of date and need fixed.
|-
| '''"Invalid value for <parameter>"''' means Report Commander received an invalid value for the listed parameter. Usually this just means you forgot to fill a parameter out, but could be caused by by an outdated report / adders. || Make sure all parameters are filled out.
|-
| '''"Parameter not found in report: <parameter>"''' means that a parameter was passed to the report that the report doesn't expect. || If caused by an out-of-date report (more common), update the report. If caused by out-of-date adders, re-run adders.
|-
| '''"Missing parameter values"''' means that the report was not passed all expected parameters. Normally, this is because a parameter was added to the report, and the adders are out of date. || Re-run adders.
|-
|| (I can't remember the error message) || Missing / invalid ODBC configuration. I think this presents as "could not connect to the database" or something to that effect. Sometimes it'll give you a "database vendor code" just like ITrack desktop. || Depending on the error code, Brian can make sure the ODBC connection is valid, and give Charles the name to check that the ODBC connection name in the Crystal Server config is correct. But some error codes like 1064 are unrelated to the odbc setup
|-
|| Invalid Report || The Crystal Server failed to find the report with the specified name/type. || Make sure the report exists in the customer database with the given name and type, and a valid <code>report.fileid</code>. In Presage, there used to be a bug where running reports with a non-English language selected would fail with this error.
|-
|| The file or directory is corrupted and unreadable || This would come up every so often because the D drive on Bunnahabhain was failing. It shouldn't happen anymore. || It shouldn't happen again, but if it does, delete the cached report file from <code>M:\report_cache</code> on Bunnahabhain. Maybe reupload the report if it persists after that.
||-
|| <code>Database Vendor Code (code)</code> || There was some MySQL error. Look up the error code. || Might depend on the error code, but it's probably because of a bad query in the report. Reupload report.
|}

== Logs ==

The log file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\crystalserverservice.log</code>

A normal log entry for a report job looks like this:

<pre>
Connection created for 'hosteddb-southeast.isoftdata.com.373487'
args [
'-report="D:\\Node\\crystal-reports-server\\cache\\A95AC82D42C7A2A9AFF9F720DA5F3159.rpt"',
'-login!={server:reporting_hosted_southeast}{database:373487}',
'-exportfile="D:\\Node\\crystal-reports-server\\cache\\output\\default_invoice_2024-12-03T19-20-25.872Z.pdf"',
'-exportformat="PDF"',
'-namedparameters invoicenum="5150"'
]
Destroying connection for 'hosteddb-southeast.isoftdata.com.373487'
</pre>

If you see a message like this, then the Crystal Server (not ODBC) failed to connect to the database, and there will probably be a logged request body right below it. The logged request body should have the db host sent from the application, which can be compared to the valid hosts in the config file

<pre>
Destroying connection for 'iceriver.presageanalytics.com.UNKNOWN DATABASE'
</pre>

The most common errors you'll see start like this and will show the command used to run Report Commander as well as a more-detailed error message in a mess of JSON.

<pre>
ReportError: A Report Commander error has occurred
</pre>

== Configuration ==

This will go over how to configure a customer on the Crystal Server, not so much how to deploy and configure a new Crystal Server.

The config file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\config.json</code>

=== Chromium ===

Does not have to be configured per-customer. One config per VM. The users have more security and so they use more of the SSL options than other users

=== Presage Web/API ===

<code>REPORT_SERVER_URI</code> specifies the report server URI used by the server, and <code>MYSQL_HOST</code> specifies the DB host. <code>EXTERNAL_DB_HOST</code> will be sent to the Crystal Server instead of <code>MYSQL_HOST</code>, if specified. '''Either <code>MYSQL_HOST</code> or <code>EXTERNAL_DB_HOST</code> MUST match the <code>host</code> in the Crystal Server config file or it will not work!'''

==== SMB ====

Currently (12/04/2024), Culligan GI is the only Presage SMB customer, and was configured individually. Maybe in the future, Presage SMB will work like Chromium and just have one config per VM, but that's not currently the case.

Since the setup for SMB clients is slightly different, the <code>MYSQL_HOST</code> is an "internal" IP, but we need an external host that matches what the Crystal Server knows. To get around this, specify this ENV variable:<code>EXTERNAL_DB_HOST: <customername>-database.presageanalytics.com</code>. Make sure the URL matches the one in the Crystal Server config. Apparently, SMB DB URLs will always have <code>-database</code> in them since the SMB docker containers don't run on the same iron as MySQL.

As of 02/03/2025, there's also Bartlett, which had some issues setting it up related to SSL. Brian fixed it, I'm not sure what he did. I think they're also set up slightly differently than Culligan GI

==== Self-Hosted ====

If they're okay hitting our Crystal Server, we just need to make sure that their database can be reached on Bunnahabhain, then the setup is the same as a hosted yard.

If not, we'll have to deploy it to a Windows server they control, and set the <code>REPORT_SERVER_URI</code> ENV variable in the API to the proper URI. Presage API will have to be able to reach <code><The Server URL>/process_report</code> in order to generate the reports

=== Enterprise Web/API ===

If we host the customer, we should just set them up on our Crystal Server. Follow the general steps for configuring them in the Crystal Server config.json, then set some ENV variables in Portainer:

* <code>REPORT_SERVER_URI: http://print.itrackchromium.com</code>
* <code>EXTERNAL_DB_HOST: example-url.itrackenterprise.com</code>

WG is currently (3/11/25) the only EE customer with the web report viewer on, and they also had to have the caPath set in the crystal server config to the old/not-2024 ca cert. Not sure if that'll be true for other EE customers, but it was for them.

If they're self hosted, and don't want to use our Crystal Server, follow the steps under "Deployment", then set the above ENV variables to the proper values for their setup.

== Updating ==

Not 100% sure since it's been awhile, but I'm pretty sure the process is basically:
1. Build the Crystal Server to an exe again
2. Replace the old exe on BH
3. Restart CrystalServer service

== Deployment ==

For 99% of customers, this section will not apply. But in the event that a self-hosted customer wants to host their own Crystal Server, this is probably how.

* Locate a Windows Server
* Install Report Commander on it
* Run CrystalServerSetup.exe from dl.isoftdata.com, I think this sets up the service to make it run in the background and on startup?
* Get the latest EXE or build a new one from https://github.com/ISoft-Data-Systems/crystal-reports-server and replace the old EXE from the installer
* Restart the CrystalServer service
* Make sure the service is reachable from wherever the Presage API is running
* At this point, they should be able to make a request to <code>serveruri</code>/process_report and get a report back.

== Misc / Notes ==

Housby has Crystal Server deployed to generate invoice PDFs for an ecommerce integration. They're using a version before we compiled it to an exe, so if they ever run into bugs or need an update it will be a little different

Web Report Viewer Troubleshooting

2025-03-11T19:09:03Z

Ckaup: /* Enterprise Web/API */

This article applies to Presage Web and ITrack Chromium. The web Report Viewer will give a general error, error details are logged to the reportqueue table and can be viewed in the "History" (web) or "Print Queue" (desktop) tab of the Report Viewer screen.

== Terms ==

* Crystal Server - the Node.JS application that uses Report Commander to generate the report PDF. Runs on Bunnahabhain
* Report Commander - command line application used to generate report PDFs by the Crystal Server (and Report Queue)
* Report Queue - python application that reads from reportqueue table to send emails and print to a printer. '''Report Queue is separate from Crystal Server, and the two systems do not interact.'''
* reportqueue - a table in the database that logs report runs.
* reportparameter - a table in the database that associates parameters to reports

== Common Errors ==

=== Error Running Report ===

This means that Report Commander encountered an error running the report. If you get this error, check the reportqueue error for a more detailed error message. Listed below are some common ones.

==== "Missing parameter values" or "Double check the parameters..."====

This means that Report Commander did not receive all required parameters for the report. Often times, the report will run fine on desktop, because the Crystal SDK can "fill in the gaps", while the web Report Viewer cannot, and needs a row in reportparameter for every parameter.

===== Solution =====

Since this is caused by missing rows in the reportparameter table, re-running the adder scripts will generally fix the issue.

If it doesn't, the adder script could be out of date or otherwise missing parameters.

==== Parameter not found in report: <parametername> ====

This means that a report was passed a parameter it doesn't expect.

===== Solution =====

Make sure the report is up to date

==== (I can't remember the error message) ====

Missing / invalid ODBC configuration. I think this presents as "could not connect to the database" or something to that effect.

===== Solution =====

Brian can make sure the ODBC connection is valid, and give Charles the name to check that the ODBC connection name in the Crystal Server config is correct.

==== Invalid Value for <parameter> ====

Report Commander received an invalid value for the specified parameter

=== Invalid Session ===

This error is caused by the Crystal Server failing to verify the session token it was passed.

==== Solution ====

Most likely, if logging out and back in doesn't fix it, this means that the Crystal Server configuration is either missing, or configured with a different database host URL than the API. Charles can check the logs to double check, as well as update the config file. Brian can then restart the Crystal Server service to load the updated configuration.

=== Invalid Report ===

The Crystal Server failed to find the report with the specified name/type. Or, the report is missing its corresponding <code>file</code> data.

=== The file or directory is corrupted and unreadable ===

Once or twice the cached .rpt file on Bunnahabhain was corrupted or something. We fixed it by reuploading the report to the customer's db and deleting the cached .rpt file from <code>\\192.168.5.18\Node\crystal-reports-server\cache</code>

It's possible it was because the D drive was failing. Cache has been moved to M:\report_cache

=== Other Errors ===

<code>Error: WARNING: MYSQL_OPT_RECONNECT is deprecated and will be removed in a future version.</code> - Disable "Auto Reconnect" on ODBC. Presents as "Unkown Error" or "Internal Server Error" in the UI

== Common Errors (Table Mode)==

{| class="wikitable" style=""
|+ Common Errors
|-
! style="min-width: 100px;"| Error !! Description !! How to Fix
|-
| Invalid Session. Try logging out and logging back in. || This means that the report server was not able to verify your session. Either your session has expired, or the Crystal Server is not configured for that database. The most likely cause of this is, if logging out and back in doesn't fix it, is that the (generally Presage) customer hasn't been set up on the Crystal Server, or some configuration has changed. || If the config for that customer is missing, then add it matching the template. If it is present, make sure that the Crystal Server and Chromium/Presage API are configured with the same DB URL. Otherwise, check the ODBC connection and DB credentials. Charles can check the logs to double check the URLs are good, as well as update the config file. Brian can then restart the Crystal Server service to load the updated configuration.
|-
| rowspan="4" |Error running report. Double check the report parameters and try again. || This means that Report Commander did not receive the correct amount of parameters for the report. Often times, the report will run fine on desktop, because the Crystal SDK can "fill in the gaps" or ignore extra parameters, while the web Report Viewer cannot, and needs a row in reportparameter for every parameter. Check the <code>Report Viewer > History</code> tab for more error details || Generally, update the report and re-run adders, but '''See Below''' for more details, and check <code>Report Viewer > History</code> for more parameter and error details. If updating the report and adder doesn't fix it, it's possible that they are out of date and need fixed.
|-
| '''"Invalid value for <parameter>"''' means Report Commander received an invalid value for the listed parameter. Usually this just means you forgot to fill a parameter out, but could be caused by by an outdated report / adders. || Make sure all parameters are filled out.
|-
| '''"Parameter not found in report: <parameter>"''' means that a parameter was passed to the report that the report doesn't expect. || If caused by an out-of-date report (more common), update the report. If caused by out-of-date adders, re-run adders.
|-
| '''"Missing parameter values"''' means that the report was not passed all expected parameters. Normally, this is because a parameter was added to the report, and the adders are out of date. || Re-run adders.
|-
|| (I can't remember the error message) || Missing / invalid ODBC configuration. I think this presents as "could not connect to the database" or something to that effect. Sometimes it'll give you a "database vendor code" just like ITrack desktop. || Depending on the error code, Brian can make sure the ODBC connection is valid, and give Charles the name to check that the ODBC connection name in the Crystal Server config is correct. But some error codes like 1064 are unrelated to the odbc setup
|-
|| Invalid Report || The Crystal Server failed to find the report with the specified name/type. || Make sure the report exists in the customer database with the given name and type, and a valid <code>report.fileid</code>. In Presage, there used to be a bug where running reports with a non-English language selected would fail with this error.
|-
|| The file or directory is corrupted and unreadable || This would come up every so often because the D drive on Bunnahabhain was failing. It shouldn't happen anymore. || It shouldn't happen again, but if it does, delete the cached report file from <code>M:\report_cache</code> on Bunnahabhain. Maybe reupload the report if it persists after that.
|}

== Logs ==

The log file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\crystalserverservice.log</code>

A normal log entry for a report job looks like this:

<pre>
Connection created for 'hosteddb-southeast.isoftdata.com.373487'
args [
'-report="D:\\Node\\crystal-reports-server\\cache\\A95AC82D42C7A2A9AFF9F720DA5F3159.rpt"',
'-login!={server:reporting_hosted_southeast}{database:373487}',
'-exportfile="D:\\Node\\crystal-reports-server\\cache\\output\\default_invoice_2024-12-03T19-20-25.872Z.pdf"',
'-exportformat="PDF"',
'-namedparameters invoicenum="5150"'
]
Destroying connection for 'hosteddb-southeast.isoftdata.com.373487'
</pre>

If you see a message like this, then the Crystal Server (not ODBC) failed to connect to the database, and there will probably be a logged request body right below it. The logged request body should have the db host sent from the application, which can be compared to the valid hosts in the config file

<pre>
Destroying connection for 'iceriver.presageanalytics.com.UNKNOWN DATABASE'
</pre>

The most common errors you'll see start like this and will show the command used to run Report Commander as well as a more-detailed error message in a mess of JSON.

<pre>
ReportError: A Report Commander error has occurred
</pre>

== Configuration ==

This will go over how to configure a customer on the Crystal Server, not so much how to deploy and configure a new Crystal Server.

The config file lives at:

<code>\\192.168.5.18\Node\crystal-reports-server\config.json</code>

=== Chromium ===

Does not have to be configured per-customer. One config per VM. The users have more security and so they use more of the SSL options than other users

=== Presage Web/API ===

<code>REPORT_SERVER_URI</code> specifies the report server URI used by the server, and <code>MYSQL_HOST</code> specifies the DB host. <code>EXTERNAL_DB_HOST</code> will be sent to the Crystal Server instead of <code>MYSQL_HOST</code>, if specified. '''Either <code>MYSQL_HOST</code> or <code>EXTERNAL_DB_HOST</code> MUST match the <code>host</code> in the Crystal Server config file or it will not work!'''

==== SMB ====

Currently (12/04/2024), Culligan GI is the only Presage SMB customer, and was configured individually. Maybe in the future, Presage SMB will work like Chromium and just have one config per VM, but that's not currently the case.

Since the setup for SMB clients is slightly different, the <code>MYSQL_HOST</code> is an "internal" IP, but we need an external host that matches what the Crystal Server knows. To get around this, specify this ENV variable:<code>EXTERNAL_DB_HOST: <customername>-database.presageanalytics.com</code>. Make sure the URL matches the one in the Crystal Server config. Apparently, SMB DB URLs will always have <code>-database</code> in them since the SMB docker containers don't run on the same iron as MySQL.

As of 02/03/2025, there's also Bartlett, which had some issues setting it up related to SSL. Brian fixed it, I'm not sure what he did. I think they're also set up slightly differently than Culligan GI

==== Self-Hosted ====

If they're okay hitting our Crystal Server, we just need to make sure that their database can be reached on Bunnahabhain, then the setup is the same as a hosted yard.

If not, we'll have to deploy it to a Windows server they control, and set the <code>REPORT_SERVER_URI</code> ENV variable in the API to the proper URI. Presage API will have to be able to reach <code><The Server URL>/process_report</code> in order to generate the reports

=== Enterprise Web/API ===

If we host the customer, we should just set them up on our Crystal Server. Follow the general steps for configuring them in the Crystal Server config.json, then set some ENV variables in Portainer:

* <code>REPORT_SERVER_URI: http://print.itrackchromium.com</code>
* <code>EXTERNAL_DB_HOST: example-url.itrackenterprise.com</code>

WG is currently (3/11/25) the only EE customer with the web report viewer on, and they also had to have the caPath set in the crystal server config to the old/not-2024 ca cert. Not sure if that'll be true for other EE customers, but it was for them.

If they're self hosted, and don't want to use our Crystal Server, follow the steps under "Deployment", then set the above ENV variables to the proper values for their setup.

== Updating ==

Not 100% sure since it's been awhile, but I'm pretty sure the process is basically:
1. Build the Crystal Server to an exe again
2. Replace the old exe on BH
3. Restart CrystalServer service

== Deployment ==

For 99% of customers, this section will not apply. But in the event that a self-hosted customer wants to host their own Crystal Server, this is probably how.

* Locate a Windows Server
* Install Report Commander on it
* Run CrystalServerSetup.exe from dl.isoftdata.com, I think this sets up the service to make it run in the background and on startup?
* Get the latest EXE or build a new one from https://github.com/ISoft-Data-Systems/crystal-reports-server and replace the old EXE from the installer
* Restart the CrystalServer service
* Make sure the service is reachable from wherever the Presage API is running
* At this point, they should be able to make a request to <code>serveruri</code>/process_report and get a report back.

== Misc / Notes ==

Housby has Crystal Server deployed to generate invoice PDFs for an ecommerce integration. They're using a version before we compiled it to an exe, so if they ever run into bugs or need an update it will be a little different

Web Report Viewer Troubleshooting

2025-03-11T19:02:12Z

Ckaup: /* Enterprise Web/API */

Web Report Viewer Troubleshooting

2025-03-11T19:01:57Z

Ckaup: /* Enterprise Web/API */

Web Report Viewer Troubleshooting

2025-02-18T22:14:39Z

Ckaup: /* Self-Hosted */

Web Report Viewer Troubleshooting

2025-02-18T22:13:11Z

Ckaup: /* SMB */

Web Report Viewer Troubleshooting

2025-02-05T17:16:13Z

Ckaup: /* Common Errors (Table Mode) */

Web Report Viewer Troubleshooting

2025-02-03T17:19:25Z

Ckaup: /* SMB */

Web Report Viewer Troubleshooting

2025-01-16T18:11:00Z

Ckaup: /* Deployment */

Web Report Viewer Troubleshooting

2025-01-16T18:10:09Z

Ckaup: /* Deployment */

Web Report Viewer Troubleshooting

2025-01-16T18:09:10Z

Ckaup:

Web Report Viewer Troubleshooting

2025-01-14T17:48:54Z

Ckaup: /* Common Errors (Table Mode) */

Web Report Viewer Troubleshooting

2025-01-14T17:48:21Z

Ckaup: /* Invalid Report */

Web Report Viewer Troubleshooting

2024-12-19T22:56:19Z

Ckaup: /* Common Errors (Table Mode) */

Web Report Viewer Troubleshooting

2024-12-19T20:47:04Z

Ckaup: /* Common Errors (Table Mode) */

Web Report Viewer Troubleshooting

2024-12-19T20:42:28Z

Ckaup: /* The file or directory is corrupted and unreadable */

Web Report Viewer Troubleshooting

2024-12-10T20:09:47Z

Ckaup: /* Logs */

Web Report Viewer Troubleshooting

2024-12-10T20:07:37Z

Ckaup: /* Misc / Notes */

Web Report Viewer Troubleshooting

2024-12-10T19:37:06Z

Ckaup: