Skip to content

Commit

Permalink
Merge branch '6.0/dashboard-chart-emails'
Browse files Browse the repository at this point in the history
  • Loading branch information
@cbrandtbuffalo
cbrandtbuffalo committed Jan 24, 2025
2 parents b15be31 + b466fa6 commit 4a9f2d3
Show file tree
Hide file tree
Showing 31 changed files with 409 additions and 916 deletions.
6 changes: 4 additions & 2 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -145,11 +145,13 @@ RT is commercially-supported software. To purchase hosting, support, training, c
also require external source libraries, so you may need to install
additional packages.
If you are having trouble installing GD, refer to "Installing GD libraries"
in [docs/charts.pod](https://docs.bestpractical.com/rt/latest/charts.html).
Ticket relationship graphing requires the graphviz
library which you should install using your distribution's package manager.
Dashboard emails containing charts require a Chrome-based browser
to be installed on the RT server. Most distributions have a package
for "chromium".
See [docs/rt_perl.pod](https://docs.bestpractical.com/rt/latest/rt_perl.html)
for additional information about installing perl and RT's dependencies.
Expand Down
28 changes: 14 additions & 14 deletions configure.ac
View file
Original file line number Diff line number Diff line change
Expand Up @@ -275,20 +275,6 @@ else
fi
AC_SUBST(RT_GRAPHVIZ)

dnl RT's GD pie and bar charts
AC_CHECK_PROG([RT_GD], [gdlib-config], "yes", "no")
AC_ARG_WITH(gd,[],RT_GD=$withval)
AC_ARG_ENABLE(gd,
AS_HELP_STRING([--enable-gd],
[Turns on support for RT's GD pie and bar charts]),
RT_GD=$enableval)
if test "$RT_GD" = yes; then
RT_GD="1"
else
RT_GD="0"
fi
AC_SUBST(RT_GD)

dnl RT's GPG support
AC_CHECK_PROG([RT_GPG_DEPS], [gpg], "yes", "no")
if test "$RT_GPG_DEPS" = yes; then
Expand Down Expand Up @@ -354,6 +340,20 @@ else
fi
AC_SUBST(RT_EXTERNALAUTH)

dnl Dependencies for dashboard chart emails
AC_ARG_WITH(dashboard-chart-emails,[],RT_DASHBOARD_CHART_EMAILS=$withval,RT_DASHBOARD_CHART_EMAILS="0")
AC_ARG_ENABLE(dashboard-chart-emails,
AS_HELP_STRING([--enable-dashboard-chart-emails],
[Add dependencies needed for dashboard chart emails]),
RT_DASHBOARD_CHART_EMAILS=$enableval,
RT_DASHBOARD_CHART_EMAILS=$RT_DASHBOARD_CHART_EMAILS)
if test "$RT_DASHBOARD_CHART_EMAILS" = yes; then
RT_DASHBOARD_CHART_EMAILS="1"
else
RT_DASHBOARD_CHART_EMAILS="0"
fi
AC_SUBST(RT_DASHBOARD_CHART_EMAILS)

dnl ExternalStorage
AC_ARG_WITH(attachment-store,
AS_HELP_STRING([--with-attachment-store=TYPE],
Expand Down
18 changes: 18 additions & 0 deletions docs/UPGRADING-6.0
View file
Original file line number Diff line number Diff line change
Expand Up @@ -177,6 +177,24 @@ and that is the recommended configuration for full-text indexes.

=item *

While it has been possible to use JSChart to generate chart images in the RT UI,
because these images are generated client-side it hasn't been possible to include
them in dashboard emails.

It is now possible to use the optional Perl module L<WWW::Mechanize::Chrome> and
a compatible server-side web browser to create images of the JSChart graphs for
inclusion in emails.

This is accomplished by setting C<$EmailDashboardIncludeCharts> to '1' and
maybe also setting C<$ChromePath> to the path of the executable for your
chosen Chrome-based browser.

This feature has been tested on Linux servers using packaged versions of
Chrome, Chromium, Microsoft Edge, and Opera. Other Chrome-based browsers
that can run via command-line on a Linux server may also work.

=item *

[Add info about new ticket and asset configuration options here.]

=item *
Expand Down
67 changes: 2 additions & 65 deletions docs/charts.pod
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,74 +10,11 @@ RT has had charts for a long time, but many significant improvements
were made in RT 4.2. Another significant change was made in RT 5.0
when we converted the web chart library to Chart.js.

=head1 Enabling Charts

=head2 C<$EnableJSChart>

Starting in RT 5.0, by default charts are rendered by Chart.js,
a JavaScript charting library. If you'd like to disable JavaScript
rendered charts, you can set this configuration value to false. To use
GD charts instead of JS charts, set the C<--enable-gd> option
when running the configure script to install RT.

If you send charts in dashboards via email, GD is still used to
generate embedded chart images for email. If GD isn't available,
users can click on the link in email and view charts in RT.
However, the chart in RT will then show data based on the time
you click rather than capturing ticket data at the time the email
was generated.

=head2 Installing GD

While charts is a core part of RT, if you want to use GD charting in place
of JS charting then you do need to enable GD it using the C<--enable-gd>
option and install the required dependencies when you install RT.
If you didn't originally install with this flag, you can enable it by
re-running the C<configure> script from the RT distribution
(including all previous options passed to it originally) or doing the
following in your current install:

=over

=item 1

In your C<RT_SiteConfig.pm> set C<$DisableGD> to 0:

Set($DisableGD, 0);

=item 2

Run the RT dependency checker:

$ /opt/rt5/sbin/rt-test-dependencies --with-gd --verbose

=item 3

Install GD libraries

GD is an open source graphics library and it is available as a package
for most Linux systems. The package might be called C<gd>, C<gd2>, C<libgd2>,
or something similar. On some systems you will also need additional package
required to compile code using the library. The package might be called
C<gd-devel>, C<gd2-dev>, or something similar.

=item 4

Install Perl GD modules:

$ /opt/rt5/sbin/rt-test-dependencies --with-gd --install --verbose


=back
Starting in RT 6.0, charts are always rendered by Chart.js.

=head2 Chart Configuration Options

By default, RT is configured to use the "Droid Sans" font for Unicode support
across English, many western european languages, Chinese (Traditional and
Simplified), and Japanese. If you prefer to use a different font, you can
change the L<< "C<%ChartFont>"|RT_Config/ChartFont >> option.

There is also an option to use database timezone conversion for
There is an option to use database timezone conversion for
PostgreSQL, MySQL, and MariaDB to enable timezone conversion for
time-based reports. See F<docs/customizing/timezones_in_charts.pod>
for details.
Expand Down
83 changes: 41 additions & 42 deletions etc/RT_Config.pm.in
View file
Original file line number Diff line number Diff line change
Expand Up @@ -981,6 +981,47 @@ With this enabled, some parts of the email won't look exactly like RT.

Set($EmailDashboardInlineCSS, 0);

=item C<$EmailDashboardIncludeCharts>

To use the JSChart-generated images in emailed dashboards, install the
optional module L<WWW::Mechanize::Chrome> and enable this option.

You will also need a chrome-based browser installed on the RT server.
See also C<$ChromePath> and C<@ChromeLaunchArguments>.

=cut

Set($EmailDashboardIncludeCharts, 0);

=item C<$ChromePath>

This option contains the path for a compatible Chrome-based browser
executable that will be used to generate static images for JSChart
graphs for dashboard emails.

See also L<WWW::Mechanize::Chrome/launch_exe>

=cut

Set($ChromePath, 'chromium');

=item C<@ChromeLaunchArguments>

This option contains the launch arguments when initializing
L<WWW::Mechanize::Chrome>.

If you need to run L<rt-email-dashboards> as root, you probably need to add
C<--no-sandbox> to get around Chrome's restriction:

Set(@ChromeLaunchArguments, '--no-sandbox');

See also L<WWW::Mechanize::Chrome/launch_arg>

=cut

Set(@ChromeLaunchArguments, () );


=back


Expand Down Expand Up @@ -2256,27 +2297,6 @@ speed RT up a bit, at the expense of a tiny bit of data accuracy.

Set($WebFlushDbCacheEveryRequest, 1);

=item C<%ChartFont>

The L<GD> module (which RT uses for graphs) ships with a built-in font
that doesn't have full Unicode support. You can use a given TrueType
font for a specific language by setting %ChartFont to (language =E<gt>
the absolute path of a font) pairs. Your GD library must have support
for TrueType fonts to use this option. If there is no entry for a
language in the hash then font with 'others' key is used.

RT comes with two TrueType fonts covering most available languages.

=cut

Set(
%ChartFont,
'zh-cn' => "$RT::FontPath/DroidSansFallback.ttf",
'zh-tw' => "$RT::FontPath/DroidSansFallback.ttf",
'ja' => "$RT::FontPath/DroidSansFallback.ttf",
'others' => "$RT::FontPath/DroidSans.ttf",
);

=item C<$ChartsTimezonesInDB>

RT stores dates using the UTC timezone in the DB, so charts grouped by
Expand All @@ -2291,27 +2311,6 @@ At this time, this feature only applies to MySQL and PostgreSQL.

Set($ChartsTimezonesInDB, 0);

=item C<@ChartColors>

An array of 6-digit hexadecimal RGB color values used for chart series. By
default there are 12 distinct colors.

=cut

Set(@ChartColors, qw(
66cc66 ff6666 ffcc66 663399
3333cc 339933 993333 996633
33cc33 cc3333 cc9933 6633cc
));

=item C<$EnableJSChart>

Set this to 0 to disable Chart in JavaScript.

=cut

Set($EnableJSChart, 1);

=item C<$JSChartColorScheme>

The color scheme to use for Chart in Javascript. By default it's
Expand Down
10 changes: 4 additions & 6 deletions etc/cpanfile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ requires 'CGI::PSGI', '>= 0.12';
requires 'Class::Accessor::Fast';
requires 'Clone';
requires 'Convert::Color';
requires 'Imager';
requires 'Crypt::Eksblowfish';
requires 'CSS::Minifier::XS';
requires 'CSS::Squish', '>= 0.06';
Expand Down Expand Up @@ -209,12 +210,6 @@ feature 'graphviz' => sub {
requires 'IPC::Run', '>= 0.90';
};

feature 'gd' => sub {
requires 'GD';
requires 'GD::Graph', '>= 1.56';
requires 'GD::Text';
};

feature 'externalauth' => sub {
requires 'Net::SSLeay';
requires 'Net::LDAP';
Expand All @@ -223,6 +218,9 @@ feature 'externalauth' => sub {
};
};

feature 'dashboard-chart-emails' => sub {
requires 'WWW::Mechanize::Chrome';
};

# External attachment storage
feature 's3' => sub {
Expand Down
49 changes: 25 additions & 24 deletions lib/RT/Config.pm
View file
Original file line number Diff line number Diff line change
Expand Up @@ -415,15 +415,6 @@ our %META;
},
},
},
EnableJSChart => {
Section => 'General', #loc
Overridable => 1,
SortOrder => 10,
Widget => '/Widgets/Form/Boolean',
WidgetArguments => {
Description => 'Use JavaScript to render charts', #loc
},
},
JSChartColorScheme => {
Section => 'General', #loc
Overridable => 1,
Expand Down Expand Up @@ -875,18 +866,6 @@ our %META;
$self->Set( DisableGraphViz => 1 );
},
},
DisableGD => {
Type => 'SCALAR',
Widget => '/Widgets/Form/Boolean',
PostLoadCheck => sub {
my $self = shift;
my $value = shift;
return if $value;
return if RT::StaticUtil::RequireModule("GD");
$RT::Logger->debug("You've enabled GD, but we couldn't load the module: $@");
$self->Set( DisableGD => 1 );
},
},
MailCommand => {
Type => 'SCALAR',
Widget => '/Widgets/Form/String',
Expand Down Expand Up @@ -1445,9 +1424,6 @@ our %META;
RT->System->ExternalStorage($backend);
},
},
ChartColors => {
Type => 'ARRAY',
},
LogoImageHeight => {
Deprecated => {
LogLevel => "info",
Expand Down Expand Up @@ -2080,9 +2056,34 @@ our %META;
}
},
},
EmailDashboardIncludeCharts => {
Widget => '/Widgets/Form/Boolean',
PostLoadCheck => sub {
my $self = shift;
return unless $self->Get('EmailDashboardIncludeCharts');

if ( RT::StaticUtil::RequireModule('WWW::Mechanize::Chrome') ) {
my $chrome = RT->Config->Get('ChromePath') || 'chromium';
if ( !WWW::Mechanize::Chrome->find_executable( $chrome ) ) {
RT->Logger->warning("Can't find chrome executable from \$ChromePath value '$chrome', disabling \$EmailDashboardIncludeCharts");
$self->Set( 'EmailDashboardIncludeCharts', 0 );
}
}
else {
RT->Logger->warning('WWW::Mechanize::Chrome is not installed, disabling $EmailDashboardIncludeCharts');
$self->Set( 'EmailDashboardIncludeCharts', 0 );
}
},
},
EmailDashboardInlineCSS => {
Widget => '/Widgets/Form/Boolean',
},
ChromePath => {
Widget => '/Widgets/Form/String',
},
ChromeLaunchArguments => {
Type => 'ARRAY',
},
DefaultErrorMailPrecedence => {
Widget => '/Widgets/Form/String',
},
Expand Down
Loading

0 comments on commit 4a9f2d3

Please sign in to comment.