Creating reports for raw events in the Telemetry service

As an administrator, you can create reports for your chatbot application based on the raw events in the Telemetry service. You can either use the Telemetry service events that BMC Helix ITSM provides out of the box or you can create new events. Using these reports, application business analysts can understand how end users are using the chatbot application, derive statistics about a successful or unsuccessful event, monitor the chatbot metrics, and so on.

Important

BMC Helix Dashboards, a SaaS service on BMC Helix Portal is the default reporting platform available for new customers. BMC Helix Dashboards offers unified reporting and gives you a consolidated view of data from applications across your environment.
BMC Helix ITSM will not be available to new customers. However, after upgrading to BMC Helix Innovation Suite version 21.3, the existing customers will continue to get access to chatbot reports in BMC Helix ITSM.
The Telemetry version 20.08.x is not supported. Instead, use the Telemetry version 22.1.x.
For more information, see Statement-of-direction-End-of-life-plan-for-Telemetry-version-20-08-x.

Before you begin

Before you start creating reports, ensure that you have completed the following tasks:

Ensure that you have access to BMC Helix ITSM.
Instead of using out-of-the-box events, if you want to create reports for custom events, ensure that you have created the events.

Process for creating a report

The following image illustrates the different stages involved in creating a report:

2002_Process of creating chatbot reports.png

The following table describes the different tasks that are involved in the process to create a report:

Note

Tasks 1-6 are optional because instead of performing these actions, you can leverage the out-of-the-box connections and definitions provided by BMC Helix Innovation Suite. If you leverage the out-of-the-box connections and definitions, you can directly create a report in BMC Helix ITSM.

Task	Action	Reference
Establish a connection between BMC Helix Virtual Agent and a local or remote system
(Optional) 1	Create a web API connection to access the Telemetry service data on a local or remote system.	To create a web API connection
(Optional) 2	Create a data source by using the web API connection to leverage external data.	To create a data source connection
(Optional) 3	Create a data source mapping to map the data source with its alias.	To create a data source connection mapping
Define the data to be displayed in a report
(Optional) 4	Create a document definition to define the structure in which you want to get the external data.	To create a document definition
(Optional) 5	Create a REST API web request service definition to get data over a REST API call.	To create a web API request service definition
(Optional) 6	Create an external or a join record definition to access the external data.	To create an external or a join record definition
Create a report by using the data defined
7	Create a report to analyze the chatbot usage.	To create a report

Out-of-the-box definitions and connections

The following table lists the out-of-the-box definitions and connections that BMC Helix Innovation Suite provides to create reports for the Telemetry service raw data:

Type of definition or connection	Out-of-the-box data
Web API connection	Remote Web API Connection
Data source	Telemetry Data Source
Data source mapping	BMC Helix Innovation Suite maps the Telemetry Data Source with its alias as shown in the following image:
Document definitions	BMC Helix Innovation Suite provides the following out-of-the-box document definitions: Bot Transform Response Conversation response Failed Entitlement Check Response Failed Transfer To Agent Response Service Request Response Successful Transfer To Agent Response User Feedback Response Chatbot Message Monitoring Test Case Chatbot Message Monitoring Log
Web API request service definition	BMC Helix Innovation Suite provides the following out-of-the-box web API request service definitions: Service Request Event API Failed Transfer To Agent Event API Failed Entitlement Check Event API User Feedback Event API Conversation Event API Successful Transfer To Agent Event API Chatbot Message Monitoring API
External record definitions	BMC Helix Innovation Suite provides the following out-of-the-box external record definitions: Successful Transfer To Agent Raw Data Service Request Raw Data User Feedback Raw Data Failed Entitlement Check Raw Data Failed Transfer To Agent Raw Data Conversation Raw Data

(Optional) Task 1: To create a web API connection

If you do not want to use the out-of-the-box web API connection, you can create a web API connection for the Telemetry service.

To create a web API connection, see Configuring the authentication credentials of REST API web services.

(Optional) Task 2: To create a data source

If you do not want to use the out-of-the-box data source, you can create a data source for the Telemetry service to leverage the raw data.

Click to view steps to configure a data source

Log in to BMC Helix Innovation Suite and navigate to the Administration tab.
Select Connections > Data Sources.
On the Data Source Connection page, click New.
The Add New Data Source Configuration dialog is displayed.
On the General tab, complete the following fields:
- Name—Enter a meaningful name for your data source.
- Type—Select Web API as the connection type.
On the Connection Properties tab, in the Web API Connection field, select the web API connection that you created in Task 1.
Click Save.

(Optional) Task 3: To create a data source mapping

If you do not want to use the out-of-the-box data source mapping, you can create a new mapping for your data source. You map an alias (a placeholder for tenant-specific data source configuration) with the appropriate data source so that the appropriate data source configuration is used when you access data by using external record definitions.

Click to view steps to create a data source mapping

Log in to BMC Helix Innovation Studio and navigate to the Administration tab.
Select Configure My Server > Data Source.
On the Data Source Connection page, click New.
The Data Source Mapping page is displayed.
From the Application list, select the required application.
A list of aliases for the configured data sources is displayed as Connection Target.
In the Connection Configuration field, for the corresponding Connection Target, select the required data source.
Click Save.

(Optional) Task 4: To create a document definition

If you do not want to use the out-of-the-box document definition, you can create a new definition to define the structure in which you want to receive data from the web API call.

To perform the steps to create a document definition, see Defining a document schema.

(Optional) Task 5: To create a web API request service definition

If you do not want to use the out-of-the-box web API request service definition, you can create a service definition to receive data over a REST API call.

Click to view steps to create a web API request service definition

Log in to BMC Helix Innovation Studio and navigate to the Workspace tab.
Select
BMC Helix Virtual Agent
.
On the Web APIs tab, click New.
On the Properties tab, provide a name for the RESTful Service, for example, Get Telemetry Data.
On the New Web API page, perform one of the following steps:
- To add a web request to an existing Web API, click the Web API name.
- To create a new Web API, click New.

On the Settings tab, complete the fields as described in the following table:

Field	Description	Example
Name	Type a name for the web request.	Get Telemetry Raw Data Request
Request Method	Select the HTTP method of the web request.	GET
(Optional) Multipart Request	If you want a request to be of the multipart type, then select this toggle key. Note: You do not require this field while configuring the web API for chatbot reports.	None
Path	Specify the URL path on which the method is invoked. Format of the URL: /rest/api/	/rest/api/latest/issue/{issueid}
(Optional) Body	From the list, select the document definition that you created earlier from which you want to copy the body in JSON format. Typically, this is needed for the POST or PUT methods and might not be required for other methods. Note: You do not require this field while configuring the web API for chatbot reports.	None
(Optional) Response	From the list, select the document definition that you created earlier from which you want to copy the response in JSON format.	None
(Optional) Add Headers	Add the headers for this web request.	None
(Optional) Query Parameters	Add the query parameters for this web request.	None

(Optional) Task 6: To create an external or a join record definition

If you do not want to use the out-of-the-box record definitions, you can create an external record definition to access the Telemetry service data.

To create an external record definition, see Creating external record definitions.

Notes

When you create an external record definition for a web API, the system generates the fields for header, query parameters, path parameters, and body in the web API. For a system generated field, if you give a default value, at run time, the default value is used. If you want to override this value, you can define different values at run time.
In
BMC Helix ITSM
, while creating a report, you can define values for system generated fields by using filters.
If you are creating a report for a custom event statistics, a regular record definition is automatically created.

If you want to combine data from multiple external record definitions or is you want to creating a report for a custom event, you must create a join record definition.

To perform the steps to create a join record definition, see Creating join record definitions.

Note

While creating a join record definition, on the Field Selection tab, ensure that you select the fields that the system generates for the web API header, query parameters, path parameters, and body.

Task 6: To create a report

You must first create a view for a report and then add the data that you want to display in the report.

Click to view the steps to create a view
1. Log in to BMC Helix Innovation Studio and click Reports.
2. Click and select View.
3. In the Create New View dialog box, complete the following fields:
  Select AR System as the data source.
  Select Single Table as your view type.
  From the Select Table list, search for the required external record definition.
  Note: The Select Table list shows the available out-of-the-box and custom external record definitions for the Telemetry service raw data.
  Enter the view name and description.
  From the Create Analysis list, either select Save & Close, or select Create Analysis to start creating the report using this view.
Click to view steps to create a report
1. Log in to BMC Helix Innovation Studio and click Reports.
2. Click and select Report.
3. In the New Report dialog box, select a view for your report, and start creating the report.
  Note: In the Data section, the Dimensions list shows the fields from the record definition that you selected while creating the view.
  For information about how to create a report, see Create custom reports.
4. After you create the report, perform any of the following actions:
  To save the report, click the Report tab, and click Save or Save as.
  The Save Report dialog box is displayed.
  To publish the report, click the Publish tab.
  The Save Report dialog box is displayed.
  To complete the fields in the Save Report dialog, see Saving and providing access to reports.
The following image shows the fields from an external record definition in the report as filters, rows, or columns:

You have now established a connection between BMC Helix Virtual Agent and the raw data source, defined the data to be added to the report, and created a view definition to display the reports.