Embedding reports in Jelly

You can embed reports in any Jelly-based element, such as a UI page.

Enabling Embedding

To enable embedding reports in Jelly, add the following element to your Jelly code.

<g:inline template="reporting_includes.xml" />

After adding this code, you can embed an existing report, or generate a report within the Jelly code.

Embedding an existing report

You can embed an existing report by calling the embedReportById(targetSpan, reportId) function.

For example:
<xml version="1.0" encoding="utf-8">
     <j:jelly trim="false" xmlns:j="jelly:core" xmlns:g="glide" xmlns:j2="null" xmlns:g2="null">
     <g:inline template="reporting_includes.xml" />
     <div id="report_stuff" />
     </j:jelly?>

var div = $j("#report_stuff");
embedReportById(div, <report sys_id>);
Alternatively, you can embed the JavaScript in the jelly code:
<xml version="1.0" encoding="utf-8">
     <j:jelly trim="false" xmlns:j="jelly:core" xmlns:g="glide" xmlns:j2="null" xmlns:g2="null">
     <g:inline template="reporting_includes.xml" />
     <div id="report_stuff" />     
     <script>
          var div = $j("#report_stuff");
          embedReportById(div, <report sys_id>);
     </script>
     </j:jelly>
Table 1. Parameters
ParameterDescription
targetSpanThe jQuery element to embed the chart in. The chart uses the size of this element.
reportIdThe sys_id of the report you want to embed.

Generate and embed a report

You can embed a report within the UI by calling the embedReportByParams(targetSpan, parms) function. When embedding a report in this way, you can generate a new report using parameters, or specify a report sys_id to display that report.

For example:
<xml version="1.0" encoding="utf-8">
     <j:jelly trim="false" xmlns:j="jelly:core" xmlns:g="glide" xmlns:j2="null" xmlns:g2="null">
     <g:inline template="reporting_includes.xml" />
     <div id="report_stuff" />
     </j:jelly>
var params = {sysparm_title: "Average for all ratings", sysparm_field: "category", sysparm_type: "bar", sysparm_table: "asmt_category_result", sysparm_aggregate: "AVG", sysparm_sumfield: "rating"}; 
var div = $j("#report_stuff");
embedReportByParams(div, params);
Alternatively, you can embed the JavaScript inside the jelly code:
<xml version="1.0" encoding="utf-8">
     <j:jelly trim="false" xmlns:j="jelly:core" xmlns:g="glide" xmlns:j2="null" xmlns:g2="null">
     <g:inline template="reporting_includes.xml" />
     <div id="report_stuff" />
     <script>
          var params = {sysparm_title: "Average for all ratings", sysparm_field: "category", sysparm_type: "bar", sysparm_table: "asmt_category_result", sysparm_aggregate: "AVG", sysparm_sumfield: "rating"};
          var div = $j("#report_stuff");
          embedReportByParams(div, params);
     </script>
     </j:jelly>
Table 2. Parameters
Parameter Description
targetSpan The jQuery element to embed the chart in.
parms A JSON object defining the report. Available parameters depend on the report type.

Embedded report parameters

When embedding a report in a Jelly element, you can define a report at any time by passing parameters.

Common parameters

Certain parameters are used by multiple report types.

Table 3. Common parameters
Parameter Description Default value
jvar_report_id The sys_id of a report record. If you pass this parameter, do not specify any other parameters. All values are taken from the report record.
sysparm_title The title of the report.
sysparm_table The table to report on. Specify this value or sysparm_report_source_id, but not both.
sysparm_report_source_id The sys_id of a report source. Specify this value or sysparm_table, but not both. This value is used instead of sysparm_table if you pass both.
sysparm_type The type of report to create.

Possible values are: list, line, line_bar, area, spline, bar, horizontal_bar, pareto, hist, pie, donut, semi_donut, angular_gauge, solid_gauge, pivot, pivot_v2, funnel, calendar, pyramid, box, trend, control, tbox, and heat map.

line
sysparm_field The field from the specified table to group data by. This value is required for time series, column, bar, pie, donut, funnel, pyramid, box, trend, and trend box reports. This value is optional for list reports.
sysparm_query The filter to apply to the data before generating the report. Specify a query string for this value.
sysparm_aggregate The aggregation type.

Possible values are: AVG, COUNT, SUM, and COUNT_DISTINCT

COUNT
sysparm_sumfield The field to aggregate data on. This parameter does not apply when using a COUNT aggregation type.
sysparm_display_grid A boolean value that controls whether the report displays a data grid. false
sysparm_show_other A boolean value that controls whether the Other group appears on the report. This group appears only if the number of groups exceeds the number specified in the sysparm_others parameter. This parameter applies to bar, pie, funnel, pyramid, pivot, and heat map reports. true
sysparm_others The maximum number of individual groups of data to display. Any additional data groups are combined into the Other group. This parameter applies to bar, pie, funnel, pyramid, pivot, and heat map reports.
sysparm_show_empty A boolean value that controls if records with empty grouping or trend values appear on the report. false
sysparm_stack_field The field used to control stacking on bar and column reports.
sysparm_bar_unstack A boolean value that controls if stacked data is presented as a single bar or column, or as multiple bars. false
sysparm_box_field The numeric field used to measure the data. This parameter is required for box and histogram reports.
sysparm_trend_field The date-time field used to organize trend data. This parameter is required for time series, trend, and box reports.
sysparm_trend_interval The interval to measure trend values by.

Possible values are: year, quarter, month, week, dayofweek, hour, and date.

year
sysparm_compute_percent The value to use when displaying report percentages. You can display percentages based on the total record count, or by the specified aggregate.

Possible values are: aggregate and count

count
sysparm_use_color_palette A boolean value that controls if a full color palette is used to render the report. The value of the property glide.ui.report.use_full_color_palette or false if this property is undefined.
sysparm_funnel_neck_percent A number 1–100 that defines the percentage of a funnel report that is the neck of the funnel. 30
sysparm_show_report_data_label A boolean value that controls if data labels appear on the report. false
sysparm_show_zero A boolean value that controls if zeroes appear on multipivot and heat map reports.
sysparm_ct_row The field used to define the rows in heat map and bubble reports.
sysparm_ct_column The field used to define the columns in heat map and bubble reports.
sysparm_y_axis_category_fields The field used to define the rows in multipivot reports. Specify up to five comma-separated field names.
sysparm_x_axis_category_fields The field used to define the columns in multipivot reports. Specify up to three comma-separated field names.
sysparm_list_ui_view The sys_id of a list view to use when a user drills into the report.
sysparm_show_marker A boolean value that controls if markers appear at every plotted point on a report. true

Service catalog parameters

Certain parameters apply only to reports created on service catalog tables, such as the Requested Item [sc_req_item] table. These parameters are not available on list or calendar type reports.
Table 4. Service catalog report parameters
sysparm_sc_groupby_item_id The sys_id of a catalog item. Use this parameter with the sysparm_sc_groupby_variable_id parameter to group a service catalog report based on a catalog variable value. These parameters replace the sysparm_field parameter when grouping on service catalog variables.
sysparm_sc_groupby_variable_id The sys_id of the catalog item variable used to determine how data is grouped on the report. This variable must belong to the catalog item specified in the sysparm_sc_groupby_item_id parameter.
sysparm_sc_stackby_item_id The sys_id of a catalog item. Use this parameter with the sysparm_sc_stackby_variable_id parameter to stack a service catalog report based on a catalog variable value. These parameters replace the sysparm_stack_field parameter when grouping on service catalog variables. Only reports that support stacking, such as bar reports, support these parameters.
sysparm_sc_stackby_variable_id The sys_id of the catalog item variable used to determine how data is grouped on the report. This variable must belong to the catalog item specified in the sysparm_sc_stackby_item_id parameter.

Chart-specific parameters

Certain parameters are available only for specific report types.

Table 5. Donut report parameters
Parameter Description Default value
sysparm_show_report_total A boolean value that controls if the total score of the grouped donut appears in the center of the report. false
sysparm_donut_width_percent A number 1–100 that controls the thickness of the donut report. 50
Table 6. Heatmap parameters
Parameter Description Default value
sysparm_use_color_heatmap A boolean value that controls if the heatmap uses a gradient to color the report. When true, the sysparm_axis_max_color and sysparm_axis_min_color values are used. true
sysparm_axis_max_color The color used in the heatmap gradient to indicate a high value. This value must be the sys_id of a Color Definition [sys_report_color] record. UI14 blue
sysparm_axis_min_color The color used in the heatmap gradient to indicate a low value. This value must be the sys_id of a Color Definition [sys_report_color] record. white
Table 7. Dial parameters
Parameter Description Default value
sysparm_gauge_autoscale A boolean value that controls if the dial automatically calculates the minimum and maximum scale on the report. If you set this value to false, you must specify a sysparm_from and sysparm_to value. true
sysparm_from A number that defines the minimum value for the axis scale.
sysparm_to A number that defines the maximum value for the axis scale.
sysparm_upper_limit A number that defines the upper threshold for the dial. If you do not specify a value, the dial has no upper threshold.
sysparm_lower_limit A number that defines the lower threshold for the dial. If you do not specify a value, the dial has no lower threshold.
sysparm_direction A value that controls which values are considered positive on the report, lower values or higher values.

Possible values are: minimize and maximize.

minimize

Chart size parameters

Certain parameters control the width and height of the report.
Table 8. Size parameters
Parameter Description Default value
sysparm_report_size The size of the report. Valid values are small, medium, and large. large
sysparm_custom_report_size Set this parameter to true to specify custom report height and width values instead of using one of the size options from the sysparm_report_size parameter. false
sysparm_custom_report_height The height of the report, in pixels.
sysparm_custom_report_width The width of the report, in pixels.

Chart title parameters

Certain parameters are available only for reports that display a title. These report types include time series, bar, column, pie, donut, dials, trend, box, trend box, histogram, pyramid, heat map, funnel, and control reports.
Table 9. Title parameters
Parameter Description Default value
sysparm_report_title_size A number that defines the font size of the title. 16
sysparm_report_title_color The title text color. This value must be the sys_id of a Color Definition [sys_report_color] record. black
sysparm_title_horizontal_alignment Where the title is placed horizontally relative to the report. This value is used only if sysparm_custom_report_title_position is false.

Possible values are: left, center, and right.

center
sysparm_title_vertical_alignment Where the title is placed vertically relative to the report. This value is used only if sysparm_custom_report_title_position is false.

Possible values are: top, middle, and bottom.

top
sysparm_custom_report_title_position A boolean value that controls if the report title position is defined by x and y coordinates instead of relative alignment. false
sysparm_report_title_x_position A number that defines the x position of the title on the report. This value is used only if sysparm_custom_report_title_position is true. 0
sysparm_report_title_y_position A number that defines the y position of the title on the report. This value is used only if sysparm_custom_report_title_position is true. 0

Chart border parameters

Certain parameters are available only for reports that display a border. These report types include time series, bar, column, pies, donuts, dials, trend, box, trend box, histogram, pyramid, heat map, funnel, and control reports.
Table 10. Border parameters
Parameter Description Default value
sysparm_show_report_border A boolean value that controls whether the report displays a border. false
sysparm_report_border_width A number that defines the width of the border, in pixels. 1
sysparm_report_border_radius A number that defines the radius size of the corners of the border, in pixels. 0

Legend parameters

Certain parameters are available only for reports that display a legend. These report types include pie, donut, stacked bar, stacked column, time series, trend, box, histogram, pyramid, control, and heat map reports.
Table 11. Legend parameters
Parameter Description Default value
sysparm_show_legend A boolean value that controls whether the report displays a legend. true
sysparm_legend_horizontal_alignment Where the legend is placed horizontally relative to the report.

Possible values are: left, center, and right.

center
sysparm_legend_vertical_alignment Where the legend is placed vertically relative to the report.

Possible values are: top, middle, and bottom.

bottom
sysparm_show_legend_border A boolean value that controls whether the legend displays a border. true
sysparm_legend_border_width A number that defines the width of the legend border, in pixels. 1
sysparm_legend_border_radius A number that defines the radius size of the corners of the legend border, in pixels. 0

X-axis parameters

Certain parameters are available only for reports that use an X axis. These report types include bar, horizontal bar, pareto, column, line area, spline, box, trendbox, control, and trend reports.
Table 12. X-axis parameters
Parameter Description Default value
sysparm_x_axis_title The name to display on the x axis.
sysparm_x_axis_title_size A number that defines the font size of the x-axis title.
sysparm_x_axis_title_bold A boolean value that controls whether the x-axis title text is bold. true
sysparm_x_axis_opposite A boolean value that controls if the x axis appears at the top of the report. false
sysparm_x_axis_display_grid A boolean value that controls if vertical grid lines appear from the x axis. false
sysparm_x_axis_grid_dotted A boolean value that controls whether the vertical grid lines are dotted. false
sysparm_x_axis_label_size A number that defines the font size for increment labels on the x axis. 11
sysparm_x_axis_label_bold A boolean value that controls whether the x-axis increment labels are bold. false

Y-axis parameters

Certain parameters are available only for reports that use a Y axis. These report types include bar, horizontal bar, pareto, column, line area, spline, box, trendbox, control, and trend reports.
Table 13. Y-axis parameters
Parameter Description Default value
sysparm_y_axis_title The name to display on the y axis. An automatically generated description of the report aggregation
sysparm_y_axis_title_size A number that defines the font size of the y-axis title.
sysparm_y_axis_title_bold A boolean value that controls whether the y-axis title text is bold. true
sysparm_y_axis_opposite A boolean value that controls if the y axis appears on the left of the report. false
sysparm_y_axis_display_grid A boolean value that controls if horizontal grid lines appear from the y axis. true
sysparm_y_axis_grid_dotted A boolean value that controls whether the horizontal grid lines are dotted. false
sysparm_y_axis_label_size A number that defines the font size for increment labels on the y axis. 12
sysparm_y_axis_label_bold A boolean value that controls whether the y-axis increment labels are bold. false
sysparm_y_axis_from A number defining the lowest value displayed on the y axis.
sysparm_y_axis_to A number defining the highest value displayed on the y axis.