Report Settings
On this page
Report settings hold three values: the report logo, the URL the logo links to, and the default report locale. The Admin Center and the Settings App both edit these settings, and both edit the same stored values. For how the two tools divide the work, see Admin Center and Settings App.
This page also covers ReportCmd, the command-line tool that exports a report, whether you run it yourself or a scheduled reporting job runs it, and what a database upgrade does with the supplied reports. To open, print, and add reports, see Printable Reports.
What the settings do
- Report logo. Every supplied report that shows a logo shows this one. The logo is drawn in a box half an inch high and scaled to fit the box while keeping its aspect ratio, not at its own pixel size.
- URL. In every supplied report that shows the logo, the logo is a
hyperlink to this URL. Unless you change it, the URL is
https://www.alloysoftware.com. If the URL is empty, reports still show the logo, without a link target. - Default report locale. When ReportCmd exports a report whose
definition names no language of its own, the report uses this locale; when
the setting is empty, it uses
en-US. The locale, or the report's own language, also decides the day on which a week starts for the week-based date macros of the export, such asBOWandEOWfor "This week", instead of the Windows regional settings. If no report locale is set, the Database Management tool fills it in with the default system locale of the computer it runs on.
Report Settings in the Admin Center
The Admin Center's Report Settings page holds the report logo, its URL, and the Default Locale list.
- The logo control has no command that removes the logo. Restore replaces the logo with the built-in default report logo; like any other logo change, it is stored when you save the page.
- When no locale is stored yet, Default Locale selects the first locale of the server's list as soon as the list has loaded.
Report Settings in the Settings App
In the Settings App, the settings are under General > Report Settings. The page's own tree holds a single row, Common Settings.
Change the report logo and its URL
The Report logo group holds the logo:
- Load... opens the Load logo from file... dialog. Its file filter offers BMP, JPEG, PNG, all supported images (selected by default), and all files.
- Save as... saves the current logo to a file in the logo's own format,
named
AlloyLogounless you change the name. - Clear removes the logo after the question "Are you sure you want to remove the logo?".
Save as... and Clear are available only while a logo is shown.
Enter the address the logo links to in URL:. It is saved together with the logo.
Set the default report locale
In the Default report locale group, choose the locale in Locale:. The list shows the system locales; a stored locale that is not among them is added to the list.
The Report Settings node is not included in a configuration export.
Run a report with ReportCmd
ReportCmd.exe exports one report. It runs in two ways:
- From the command line. A manual run can only write the report to a file.
- As a scheduled reporting job. Scheduled reporting is an Automation Server job of the Reporting type that runs ReportCmd.exe. A reporting job holds the report, the export format, the destination (a file, or an e-mail whose recipient can be given with workflow macros), the subject and message of that e-mail, and the report parameters.
In both ways ReportCmd shows no parameter dialog and no progress. A required report parameter that gets no value fails the run with "The report parameter '<parameter>' does not have a value. Provide a value."
Where ReportCmd is installed
ReportCmd.exe is installed in the Bin folder of the Alloy Navigator
installation folder, whatever features you choose. By default that is
<Program Files>\Alloy Software\Alloy Navigator\Bin\ReportCmd.exe; an upgraded
installation keeps the folder it was installed in before. The Automation
Server starts ReportCmd.exe from the Bin folder of the installation folder.
When the file is missing there and a copy of ReportCmd.exe is in the
Automation Server's own folder, it starts that copy.
Command-line syntax
Run ReportCmd.exe with no arguments, or with /?, /H, or /HELP, to print
its usage:
ReportCmd.exe /Report="Report_Name" [/File="Output_File"] [/Type="File_Type"] /AccessKey="Key_Name" [/Server="SQL_Server_Name" /Database="DB_Name"] [AdditionalParamName1=Value1] [AdditionalParamName2=Value2]...
| Switch | Meaning |
|---|---|
/Report |
The name of the report. Without it, or with an empty value, ReportCmd stops with "No Reports specified!"; a name that matches no report stops it with "Invalid report name '<name>'." |
/File |
The output file. The default folder is %ProgramData%\Alloy Software\<project>\Reports. The name can carry the macros listed below. |
/Type |
The export format: PDF, EXCEL, EXCELOPENXML, WORD, WORDOPENXML, or IMAGE. |
/AccessKey |
The name of a Database Access Key. |
/Server, /Database |
The SQL Server and the database. Both default to the values of the named Database Access Key. |
Name=Value |
A value for a report parameter. See Report parameters. |
Export formats
When the output file name has no extension, ReportCmd adds one by format.
Without a /Type and without a recognizable extension, the report is exported
as PDF.
/Type |
Extension added |
|---|---|
PDF |
.pdf |
EXCEL |
.xls |
EXCELOPENXML |
.xlsx |
WORD |
.doc |
WORDOPENXML |
.docx |
IMAGE |
.png |
On the command line, /Type=EXCELOPENXML and /Type=WORDOPENXML with a
/File name that has no extension, or with no /File at all, produce a file
with the .pdf extension that holds XLSX or DOCX content. A format ReportCmd does not support stops it with "Unsupported for MS
Reports export format '<format>'. See usage information."
Macros for output file names
The output file name of a job, and the /File value on the command line, can
carry these macros. They are replaced when the report is exported.
| Macro | Replaced with |
|---|---|
%YYYY |
The year |
%MM |
The month |
%DD |
The day |
%hh |
The hour |
%mm |
The minutes |
%ss |
The seconds |
%REPORTNAME |
The name of the report |
For example, a job that saves to D:\Reports\%REPORTNAME_%YYYY-%MM-%DD.pdf
writes one file per day.
A macro starts with a single percent sign. The date and time macros are
case-sensitive: %MM is the month and %mm the minutes, while %YY, %Mm,
or %SS match nothing. %REPORTNAME is matched in any letter case. A percent
sign that starts no macro is kept as it is, and ReportCmd does not turn two
percent signs into one: a name that reaches ReportCmd as %%YYYY becomes a
percent sign followed by the year. For the syntax to use inside a Windows
command file, see Generate reports in a batch on a schedule.
Report parameters
A report parameter is passed as a Name=Value token, on the command line or in
the parameter string of a reporting job:
- The name is the parameter's name in the report definition, not the prompt the Report Parameters dialog shows, and its letter case must match.
- A leading
/is optional. Double quotes are removed, and the spaces inside them are kept:/"Group By"="Due Date"arrives as/Group By=Due Date. - A token that names no parameter of the report has no effect, except
Export_Empty(see Empty reports). Two tokens for the same name fail the run. - A parameter that gets no token, or a token with nothing after
=, takes the default value of the report definition. - Separate several values with
;. A parameter that takes a single value uses only the first one. - When the parameter has a list of available values, give the value, not its label, in the same letter case. A value that is not among the available values is dropped. When none of the values is available and the parameter cannot be empty, the export fails with "The value [<values>] is not among the available values for the parameter '<prompt>'.", which names the parameter's prompt, or its name when it has no prompt.
- In a decimal value, a period is replaced with the decimal separator of the current culture.
- When a dataset query of the report uses the parameter, a value that does
not match the parameter's type fails with "The value <value> for the report
parameter '<parameter>' does not match the parameter type. Correct the value."
A Boolean value is
trueorfalse, in any letter case, so0and1fail with this message.
The names are in the report definition, the report's .rdl file: the Name
of each ReportParameter element is the name a token uses, its Prompt is
the caption the Report Parameters dialog shows, and its ValidValues holds
the value and label pairs of its list. To download the file of a summary
report, see Printable Reports.
Many supplied summary reports declare a Group_By parameter, and many a
Sort_By parameter. The Report Parameters dialog shows them by their prompts,
Group By: (Group By in one report) and Sort By:, but a command line
or a job must use the names. Where a
report offers No grouping, its value is No in some reports and None in
others. A few reports instead offer an entry labeled None, with the value
None.
Date macros for parameter values
A date and time parameter accepts these macros as its value, in any letter
case. They are expanded
when the report runs, so BOD in a scheduled job always means today, the day
on which the job runs.
| Period | Start | End |
|---|---|---|
| Today | BOD |
EOD |
| This week | BOW |
EOW |
| Last 7 days | BOL7D |
EOL7D |
| Last week | BOLW |
EOLW |
| Last 14 days | BOL14D |
EOL14D |
| This month | BOM |
EOM |
| Last 30 days | BOL30D |
EOL30D |
| Last month | BOLM |
EOLM |
| This year | BOY |
EOY |
| Last year | BOLY |
EOLY |
| All time | BALL |
EALL |
BALL and EALL pass an empty value to the report.
Reserved parameter names
These words are ReportCmd's own names, matched in any letter case: REPORT, FILE, TYPE, SERVER, DATABASE, USER,
PASSWORD, NTAUTH, WINAUTH, RUNID, LOGLEVEL, LOG, and ACCESSKEY.
A token without = has an empty name, which ReportCmd also treats as one of
these words.
- In a scheduled job, a parameter string that gives a value to a parameter with one of these names fails every run with "Failed to <action> the Scheduled Report '<job>' because the report '<report>' uses reserved words as parameter names (<names>)." The check reads the parameter string, not the report definition.
- On the command line, the first occurrence of each word is not passed to the report; a second occurrence fails the run with the same message.
Empty reports
A report can name main datasets in its definition. When every main dataset of such a report returns no rows, a scheduled or command-line export is skipped: nothing is written or sent, and the log records "No data in report. Report not exported." or "No data in report. Report not sent."
Such a report also gets the parameter Export_Empty, shown as Allow delivery
of empty reports. Export_Empty=true delivers the empty report anyway; the
default is false. The parameter is added only when the report declares at
least one parameter of its own, so an empty result of a report with main
datasets and no parameters is always skipped.
Among the supplied reports, only SSP Search List names main datasets. Its parameters:
| Name | Prompt | Values (value = label) | Default |
|---|---|---|---|
Group_By |
Group By: | Search_Date = Search Date, Person_Name = Person, Search_Scope = Search Scope |
Search_Date |
Date_From, Date_To |
Date From:, Date To: | Dates, edited as one Date Range; may be empty | None |
Scope |
Search Scope: | Several of: 0 = All, 1 = Tickets, 2 = Knowledge Base |
All three |
Show_Results |
Show Results: | -1 = All, 1 = Successful, 0 = Failed |
-1 |
Scope = 0 selects the searches made with the All scope, not every search.
Show_Results = 0 keeps the searches that found nothing, and 1 those that
found at least one result.
Results and exit codes
A successful run logs Report exported to file "<file>"., or, for a job that
e-mails the report, Report sent to "<recipient>"., where the recipient is the
text entered in the job, not the resolved list of addresses. An e-mailed report is
attached to a message that goes to the recipients the job names.
When a run fails and the database connection is open, the error is also recorded in the System Log, with the job's run ID; see Logs. A scheduled run whose job no longer exists fails with "A job with the ID '<id>' was not found."
When the Alloy Logging Engine is not installed, ReportCmd stops before it opens the database, with exit code 6. When the run has no log name, it writes "Alloy Logging Engine is not installed or its installation is corrupted."
A failed run ends with the exit code of the stage it had reached:
| Exit code | Meaning |
|---|---|
| 0 | The run finished normally. |
| 2 | The run failed before its log was started. |
| 3 | The run failed while reading its settings or connecting to the database. |
| 4 | The run failed after signing in, before the report engine was initialized. |
| 5 | The run failed after the report engine was initialized. |
| 6 | The Alloy Logging Engine is not installed. |
Generate reports in a batch on a schedule
Use a Windows command file to export several reports in one scheduled task. Each ReportCmd invocation exports one report in the format you specify.
- Create a
.bator.cmdfile on the computer where ReportCmd is installed. - Add one ReportCmd command per report, using the command-line syntax.
Use the full path to
ReportCmd.exe, the report's name, an output file, an export format, and a Database Access Key available on that computer. Supply any required report parameters. - Run the command file and check the exported files. If an export fails, use the results and exit codes to check the cause.
- In Windows Task Scheduler, create a task that launches the command file at the required interval.
NOTE: In a .bat or .cmd file, double the percent sign in output file macros:
%%YYYY, %%MM, and %%DD. Date parameter macros such as BOD and EOD
stay unchanged, without percent signs.
For example, this command in a .cmd file exports today's SSP searches to PDF.
Replace MyAccessKey with your Database Access Key name, and adjust the
installation path and output folder for your computer. Create the output folder
before running the file.
"C:\Program Files\Alloy Software\Alloy Navigator\Bin\ReportCmd.exe" /Report="SSP Search List" /File="D:\Reports\SSP-%%YYYY-%%MM-%%DD.pdf" /Type=PDF /AccessKey="MyAccessKey" Date_From=BOD Date_To=EOD
SSP Search List skips an empty report by default. Add Export_Empty=true to
create a file even when no searches match the report's filters.
You can also schedule exports through an Automation Server reporting job; see Scheduled Reports.
The Report Parameters dialog
In the Settings App, Build... in the Parameters group of a reporting job opens the Report Parameters dialog when the report has a parameter to show, and writes the values you set into the job's parameter string. For that procedure and the checks made when you save the job, see Scheduled reports in the Settings App.
The dialog shows one row per parameter, captioned with the parameter's prompt, or its name when it has no prompt. A hidden parameter gets no row. The editor depends on the parameter:
- A Boolean parameter gets a check box.
- A parameter with available values gets a drop-down list of their labels, or, when it takes several values, a checked list headed by (Select All) when it has more than one item.
- A text parameter that takes several values and has no available values gets a multi-line box, one value per line. An integer, decimal, or date and time parameter that takes several values and has no available values gets the single-value editor below, so only one value is passed.
- An integer gets a number box, a decimal number a text box, a date and time a date and time picker, and a text parameter a text box.
- A pair of date parameters named
Date_From...andDate_To...with the same ending becomes one Date Range list: Today, This week, Last 7 days, Last week, Last 14 days, This month, Last 30 days, Last month, This year, Last year, All time, and Custom date range. The row reads Date Range when the two names have no ending, Date Range followed by the number when the ending is a number, and otherwise the ending, with underscores shown as spaces.
When you open the dialog with Build..., a report with main datasets also shows Allow delivery of empty reports.
Each Date Range preset from Today to Last year fills both dates and shows them read-only, from 00:00:00 on the first day to 23:59:59 on the last. Last 7 days, Last 14 days, and Last 30 days end yesterday; This week, This month, and This year end on the last day of the period, not today. All time leaves both dates empty. Only Custom date range shows two date pickers; its end is moved to 23:59:59.
When the dialog opens, the Date Range list shows All time when neither date has a value. When both dates have values, it shows the preset whose dates match them, or Custom date range when none does.
Changing a check box, a list, a date picker, or the Date Range list reloads the parameters that depend on it; typing in a number or text box does not.
OK checks every value. A parameter that cannot be empty and has no value stops with "The report parameter '<prompt>' does not have a value. Provide a value." in a message box titled Report Viewer, and a range whose start is later than its end with "The start date is later than the end date. Correct the dates."; the dialog stays open.
Supplied reports after an upgrade
Alloy Navigator has two kinds of reports. A summary report is a list report and appears in the Reports section. A detail report belongs to one kind of object and is offered from the print menu of that object, when the report is enabled.
When a database is upgraded, each supplied report that comes with the new version is compared with the database:
- A supplied report that changed in the new version is updated in place, unless the report in the database is marked as customized.
- For a changed report that is marked as customized, the new version is added as a separate
report whose name ends with
(Updated in <version>)and which points to the report it supersedes. The customized report keeps its changes. - A supplied report that is not in the database is added. A new detail report
gets a name ending with
(New in <version>). - Added summary reports, and only those, are filed into a category created for
them:
New in Alloy Navigator <version>orUpdated in Alloy Navigator <version>. - Every loaded report is marked as updated by
Alloy Software (<version>).
Version 2026.1 adds two supplied summary reports, Reaction Time and User Session, so an upgrade to 2026.1 adds them to a database that does not hold them.
Report lists and object permissions
When a report is loaded, the custom property REQUIRED_OBJECT_PERMISSIONS of
its report definition, a comma-separated list of table names, decides for
whom the Web App's report category lists show it. A summary report is listed
for a user whose roles hold the View permission of at least one of the
matching object classes, when the license does not withhold that permission; a
report without the property is listed for everyone.
See also Permissions Reference.