Best Practices of Report

Access to reporting features and data is controlled by the user's assigned roles and application permissions. Do not assign any additional reporting role to a user with the Customer Admin role. If a reporting role is assigned, Row-Level Security (RLS) is also applied to the user, which may restrict the data available.

Apex 2.0 Reporting implements a role-based access control with three distinct roles:

Note

Only users assigned the Customer Admin role can create datasets. This role is required to set up and manage the reporting infrastructure.

For more information, refer User List.

Follow these best practices when creating datasets to ensure they are reusable, secure, and suitable for multiple reporting requirements.

1. Include the mandatory RLS columns. When creating a virtual dataset using SQL Lab, include the following columns with the exact column names:
   

   1. tenant_id

   2. assigned_workgroup_id

   3. location_id

   4. customer_id
      

      Note

      These columns are required to apply Row-Level Security (RLS) based on user permissions.

2. Design Datasets: Include the dimensions, measures, and calculated fields required for multiple charts and dashboards instead of creating a separate Dataset for each chart. This reduces duplicate datasets and provides a consistent data source for reporting.
   

3. Avoid transaction tables: Do not use transaction tables to create custom Datasets because they do not contain the required RLS columns.
   

Apply Role-Based Data Access Using RLS

Row-Level Security (RLS) controls which data appears in your reports. It automatically restricts what you see based on your assigned permissions—such as your tenant, location, customer, and workgroup—ensuring you only access data you're authorized to view.

When Setting Up Your Dataset:

1. Include the right access columns – Add these columns to your dataset based on your reporting needs:
   

   1. Tenant

   2. Location

   3. Customer

   4. Workgroup
      

2. Check the RLS matrix – Refer to the provided RLS matrix to confirm which columns are required for your specific module or report type.
   RLS automatically filters your data based on your access level. When building datasets, include the appropriate access columns and use the RLS matrix as your reference guide.

   Module	Dataset Prefix	Fields Used for RLS Filtering
   Knowledge Master	mart_km_*	tenant_id
   Problem Management	mart_pm_*	tenant_id, assigned_workgroup_id
   Service Request	mart_sr_*	tenant_id, assigned_workgroup_id, customer_id, location_id
   Change Management	mart_cm_*	tenant_id, assigned_workgroup_id
   Asset Management	mart_am_*	tenant_id
   Incident	mart_im_*	tenant_id, assigned_workgroup_id, customer_id, location_id
   CMDB	mart_cmdb_*	tenant_id, assigned_workgroup_id, customer_id
   Service Automation	mart_orc_*	none

Info

Create reusable datasets that support multiple reporting requirements and include all required RLS columns to ensure consistent and secure data access.

Use the recommended naming convention for custom datasets to ensure consistency and simplify identification and management.

Use the following naming structure:

Example:

mart_<module_code>_<custom>_<functional_name>

1. module_code: Specify the applicable module code.

2. custom: Specify customto identify the dataset as custom.

3. functional_name : Specify a descriptive name that reflects the dataset's purpose.

Note

Use descriptive functional names that clearly indicate the purpose of the dataset.

When creating a dataset using SQL Lab, apply the following expression to each date-time column to ensure the values are adjusted based on the user's time zone. The expression retrieves the GMT offset configured for the logged-in user and automatically adjusts the date-time value based on the user's time zone.

STR_TO_DATE(DATE_ADD(<column_name>, 
INTERVAL IFNULL((SELECT gmt_time_diff FROM user_timezone_mapping 
WHERE username='{{ current_username() }}'),330) MINUTE), '%Y-%m-%d %H:%i:%s.%f') <column_name>

Note

Replace <column_name> with the corresponding date-time column in the dataset.

For more information, refer Configure Time Zone Handling.

Organize related charts by using layout elements such as Rows, Columns, Headers, and Tabs. Grouping related information makes dashboards easier to navigate and interpret.

• Publish dashboards before sharing them. Publish a dashboard to make it available to other users.
  

• Copy OOB reports before customization. Do not add OOTB reports directly to Custom Dashboards. Use Save As to create a copy of the OOTB report, customize the copy, and then add it to the Custom Dashboard.

For more information, refer Create Dashboard.

Design Virtual Datasets to Include only the fields required for reports, charts, and drill-down views. Use column aliases, calculations, or transformations as needed to create a focused and reusable data source.

• Configure datasets before creating reports. Define the required fields and conditions in the virtual dataset before using it to create charts or reports.
  

• Clone reports and dashboards before editing. Only the owner can edit an existing report or dashboard. Use Save As to create a copy and make the required changes to the copy. Do not add default charts directly to custom dashboards, as future product updates to default chart configurations or logic may affect dashboards that use them..

For more information, refer Create Charts.

Dashboard filters allow you to filter the data displayed in multiple charts on a dashboard based on selected criteria. You can configure filters for specific fields, set default values, and control which charts are affected by each filter.

• View only the data relevant to your analysis.

• Apply the same filter criteria to multiple charts.

• Configure filters for specific charts based on your requirements.

• Set default filter values for a dashboard.

• Quickly change the data displayed without modifying individual charts.

For more information, refer Add and edit filter section from Create Dashboard.