Reports
Configuration - Reports
The reports element in the N2C5 Configuration file allow us to configure the reports that will be shown to users on the Reports screen.
Jarvis Plug-In’s may be used as datasets for the reports or a URL for an action. Each report must be listed separately.
Reports need to be configured by using a block like the following:
<reports output_path="/tmp">
<report access="*" folder="Subscriber Reports" name="Call Report" js="call-report.js"/>
<report access="__AdminRead" folder="Subscriber Reports" name="ACS Feature Usage" js="acs-feature-usage.js"/>
</reports>
The reports tag should only exist once in the configuration.
- output_path = “/tmp” : A location to save logs and generated files too.
The following core attributes apply to all report entries.
- access = “__AdminRead” : Comma separated groups that can run the report.
- folder = “<folder-name>“ : This is the name of the folder the report will be listed in on the report tree.
- name = “<report-name>“ : This is the name of the report.
(Mandatory)
- js = “<js file name>“ : JavaScript file to load for the report parameters and population of the user interface.
(Mandatory)
- dataset = “<dataset-name>“ : This is the dataset name which the web-client will request when the report is executed.
- action = “<uri>“ : A URI that the report can be configured to use, instead of a dataset.
- forked = “yes” : Should this report be executed in a forked way, the user will be shown its progress. When finished, the files that are generated will be downloaded. Default = “yes”. If action is set, forked should be set to “no”.
- parameter : One or more parameter elements may define the report-specific configuration values. Most options will be configured in the plugin definition for the module used.
Notes:
- A report must have a dataset or action specified.
- If an action is specified clicking
Run Report
will POST the arguments to the action URL. Progress is not able to be shown to the user, this sort of configuration may be useful to access reports from other software. - Report Plugins are normal Jarvis Plugins please see Configuration - Plugins for more detail.
Reports
Reporting on Calls Made
The CallReport module generates a report of calls made by a subscriber/card. It supports the following parameters:
<plugin dataset="call-report" access="*" module="Report::CallReport">
<parameter name="info" value="Customer Service info..."/>
<parameter name="img_path" value="/usr/share/n2c5-dev/htdocs/img/logo.jpg"/>
</plugin>
- <parameter name=“img_path” value=“{img_dir}/logo.jpg”/> : The logo image to have at the top of the report. A good size is around 201x137 pixels.
(Optional)
- <parameter name=“info” value=“Text\nInfo”/> : A string of text to show in the top left of the report. Using
\n
will cause the text to wrap onto the next row.(Optional)
Reporting on NCC ACS Feature Usage
The ACSFeatureUsage module generates the report of features used by each customer SN. It supports the following parameters:
<plugin dataset="acs-feature-usage" access="__AdminRead" module="Report::ACSFeatureUsage"/>
When emailed using the command line script EmailReport
, the following parameters are required:
- customer The Database ID of the NCC Customer. This can be retrieved from the NCC database using a query such as:
SELECT ID FROM ACS_CUSTOMER WHERE NAME like '<customer name>';
Automatically Generating and Emailing Reports
If you want to automatically generate a report and send it attached to an email regularly you can use the EmailReport
tool.
You can find the EmailReport.pl
script to automatically generate reports in the N2C5 bin
directory, /usr/share/n2c5-{release}/bin/
, where {release}
will be prod
, dev
or model
, depending on the installation version you want to use.
Usage
./EmailReport.pl ReportModuleName [-release=model|prod|dev] [-debug] [-to='user@example.com;...'] \
[-kind='Subject prefix'] [-subject='Report'] [-noextra] [param=value]
Note that if the report has no results then no emails/report will be generated.
Parameters
ReportModuleName
Must be the name of the report to run without the prefixed Report::
For example: ActivationBreakdown
will run the N2C5 Activation Breakdown report
which is available (and configured in the /etc/jarvis/
N2C5 configuration)
as Report::ActivationBreakdown
.
-release=[model|prod|dev]
The version of the configuration file to use. The configuration file
will be read from /etc/jarvis
, and the file read will be
/etc/jarvis/n2c5-{release}.xml
. This in turn will identify the source
of the report logic.
Default value for release
is dev
if not set.
-debug
Turn on debug logging.
-to='user@example.com;...'
Send email to the specified addresses. Multiple addresses can be separated using ;
.
This is required.
-kind
Specify a string to put in the subject before the Report Name in the email subject. Defaults to ‘N2C5 Report’.
-subject='email subject'
The email’s subject line will default to <kind> - <Report Name>
, where <kind>
is given by the -kind
command line argument. This argument, if given, overrides
the argument -kind
if also given.
-noextra
Specify this to disable getting extra information from the report file name to use in the auto generated subject message.
Report Parameters
To pass report parameters from the command line to the report, add the parameters
to the command line using the format <parameter name>=<value>
. E.g:
./EmailReport.pl ActivationBreakdown start_date=2015-01-01 -to=support@nsquaredsoftware.com
Required Jarvis Configuration
The following mailer configuration is required to for the report emailer. Edit the N2C5
Jarvis configuration file in /etc/jarvis/
and define the mailer configuration:
Example SMTP Mailer configuration
<!-- SMTP Mailer settings -->
<mail-sender>
<smtp>localhost</smtp>
<from>edra_analytics@your.domain</from>
<skip_bad_recipients>true</skip_bad_recipients>
</mail-sender>
Mailer Configuration Options:
- <smtp> : The SMTP server to use, it is advised to use a local relay.
(Mandatory)
- <skip_bad_recipients> : Should email continue to be sent if there are failed recipients in the to list? true or false defaults to false.
(Optional)
- <debug> : The filename to log SMTP communication to.
(Optional)
- <from> : The from address that will be used for outgoing email.
(Mandatory)
- <auth> : The authentication type to use,
EmailReport
only supportsLOGIN
andPLAIN
.(Optional)
- <authid> : The username to login to the SMTP server with.
(Optional)
- <authpwd> : The password to login to the SMTP server with.
(Optional)
The script uses the Perl module Mail::Sender
. Additional information can be found in the official documentation.