Class: AnalyticsMetric

1//JavaScript
2//Importing required modules and libraries from the Tableau Next Embedding SDK
3import {
4      AnalyticsMetric,
5      initializeAnalyticsSdk,
6	 	 analyticsEventTarget
7} from '@salesforce/analytics-embedding-sdk';
8
9analyticsEventTarget.addEventListener(EventName.ERROR, (errorEvent) => {		//Listening to global ERROR event, such as SDK or component initialization failures.
10		console.log("Received a global error event", errorEvent)				//Error details, such as error code and message, are available in the event object
11});
12
13await initializeAnalyticsSdk({                  //Configuration object for initializing the Tableau Next Embedding SDK
14    authCredential: "<%- authCredential %>",					//The frontdoor URL required for authentication
15    orgUrl: '<%- org-url %>'                    //The Salesforce org URL that hosts the Analytics component to embed.
16});
17
18const analyticsMetric = new AnalyticsMetric({
19    parentIdOrElement: '<%- parent-element %>',   					   //The parent ID or element to render the component in
20    idOrApiName: '<%- metric-id-or-api-name %>'   					   //The ID or API name of the component to embed
21});
22
23analyticsMetric.addEventListener(EventName.ERROR, (event) => {        	   //Listening to component specific ERROR event
24           console.log("Received error", event);							   //Error details (such as error code and message) are available in the event object
25      });
26
27analyticsMetric.addEventListener(EventName.COMPONENT_LOADED, () => {    //Listening to COMPONENT_LOADED event triggered when the component gets loaded
28      console.log("Component Loaded");
29});
30
31analyticsMetric.filters = [						//Sets filter property of the component to apply a filter on the embedded metric
32   {
33        fieldName: '<%- semantic-model-api-name %>.<%- field-api-name %>',	//The API name of the semantic model and the API name of the field to filter
34        values: ['<%- value %>'],											//The field value to filter the component with based on the operator <%filter-operator %>
35        operator: FilterOperator.<%filter-operator %>
36    }
37];
38
39analyticsMetric.range = {
40 	operator: FilterOperator.<%filter-operator %>,						//The date range specific operators to apply on the metric
41		values: ['<%- value %>'],											//The value may or may not be required for the date range based on the operator <%filter-operator %>
42}
43
44analyticsMetric.render();                        //Renders the metric card in the parent HTML element

1//TypeScript
2//Importing required modules and libraries from the Tableau Next Embedding SDK
3import {
4      AnalyticsMetric,
5      initializeAnalyticsSdk,
6		 analyticsEventTarget,
7      type MetricProps,
8      type AnalyticsSdkConfig
9} from '@salesforce/analytics-embedding-sdk';
10
11analyticsEventTarget.addEventListener(EventName.ERROR, (errorEvent) => {		//Listening to global ERROR event, such as SDK or component initialization failures.
12		console.log("Received a global error event", errorEvent)				//Error details, such as error code and message, are available in the event object
13});
14
15const config: AnalyticsSdkConfig = {					//Configuration object for initializing the Tableau Next Embedding SDK
16 authCredential: "<%- authCredential %>",					//The frontdoor URL required for authentication
17 orgUrl: "<%- org-url %>"							//The Salesforce org URL that hosts the Analytics component to be embedded.
18};
19await initializeAnalyticsSdk(config);			 //Initializes the Tableau Next Embedding SDK with the provided configuration and returns a promise that resolves on successful initialization.
20
21const metricProps: MetricProps = {										// Defines the properties required for configuring a metric card component.
22     parentIdOrElement: '<%- parent-element %>',   						//The parent ID or element to render the component in
23     idOrApiName: '<%- metric-id-or-api-name %>',   						//The ID or API name of the component to embed
24};
25
26const analyticsMetric: AnalyticsMetric = new AnalyticsMetric(metricProps);   //A web component for embedding an analytics metric card
27
28analyticsMetric.addEventListener(EventName.ERROR, (event) => {				//Listening to component specific ERROR event
29     console.log("Received error", event);									//Error details (such as error code and message) are available in the event object
30});
31
32analyticsMetric.addEventListener(EventName.COMPONENT_LOADED, () => {			//Listening to COMPONENT_LOADED event triggered when the component gets loaded
33     console.log("Component Loaded");
34});
35
36analyticsMetric.filters = [						//Sets filter property of the component to apply a filter on the embedded metric
37   {
38        fieldName: '<%- semantic-model-api-name %>.<%- field-api-name %>',	//The API name of the semantic model and the API name of the field to filter
39        values: ['<%- value %>'],											//The field value to filter the component with based on the operator <%filter-operator %>
40        operator: FilterOperator.<%filter-operator %>
41    }
42];
43
44analyticsMetric.range = {
45 	operator: FilterOperator.<%filter-operator %>,						//The date range specific operators to apply on the metric
46		values: ['<%- value %>'],											//The value may or may not be required for the date range based on the operator <%filter-operator %>
47}
48
49analyticsMetric.render();     					 //Renders the metric card in the parent HTML element

1// After initializing SDK with multiple orgs
2const metric1 = new AnalyticsMetric({
3  parentIdOrElement: "container1",
4  idOrApiName: "Metric1",
5  orgUrl: "https://org1.lightning.force.com", // Required in multi-org
6});
7
8const metric2 = new AnalyticsMetric({
9  parentIdOrElement: "container2",
10  idOrApiName: "Metric2",
11  orgUrl: "https://org2.lightning.force.com", // Required in multi-org
12});

1// For dashboards, the `dataSource` attribute is required in the filter input
2// to specify the data source to which the filter should be applied.
3
4await component.render();
5
6const filters: UnifiedFilterJson[] = [
7  {
8    fieldName: "Account.Name",
9    operator: FilterOperator.Equals,
10    values: ["Acme Corp"],
11    dataSource: "SalesData", // specifying data source for dashboards
12  },
13];
14
15await component.applyFilters(filters); //applies the filters to the component.

1// For metrics or visualizations, dataSource not needed.
2
3await component.render();
4
5const filters: UnifiedFilterJson[] = [
6  {
7    fieldName: "Account.Name",
8    operator: FilterOperator.Equals,
9    values: ["Acme Corp"],
10  },
11];
12
13await component.applyFilters(filters); //applies the filters to the component.

1const metric = new AnalyticsMetric({
2  parentIdOrElement: "metric-container",
3  idOrApiName: "my-metric",
4});
5
6await metric.render();
7
8const layout: MetricLayoutAttributes = {
9  componentVisibility: {
10    details: true,
11    title: true,
12    value: true,
13    comparison: true,
14    chart: true,
15    insights: true,
16    menu: true,
17    badge: true,
18  },
19};
20
21await metric.applyLayout(layout);

1const metric = new AnalyticsMetric({
2  parentIdOrElement: "metric-container",
3  idOrApiName: "my-metric",
4});
5
6await metric.render();
7
8const timeRange: MetricTimeRange = {
9  operator: "PreviousYear",
10};
11
12await metric.applyTimeRange(timeRange);
13
14// Examples of valid time range filter formats:
15// { "operator": "Yesterday" }
16// { "operator": "LastNDays", values: [30] }
17// { "operator": "CurrentYearToDate" }
18// { "operator" : "Between" , "values" : ["2019-06-26","2023-07-07"] }
19// etc.

1// For dashboards, the `dataSource` attribute is required in the filter input
2// to specify the data source to which the filter should be applied.
3
4await component.render();
5
6const filters: UnifiedFilterJson[] = [
7  {
8    fieldName: "Account.Name",
9    operator: FilterOperator.Equals,
10    values: ["Acme Corp"],
11    dataSource: "SalesData",
12  },
13];
14
15await component.applyFilters(filters); //applies the filters to the component.
16
17await component.clearFilters(); // Clears the filters applied to the component.

1// For metrics or visualizations, no need to pass dataSource.
2
3await component.render();
4
5const filters: UnifiedFilterJson[] = [
6  {
7    fieldName: "Account.Name",
8    operator: FilterOperator.Equals,
9    values: ["Acme Corp"],
10  },
11];
12
13await component.applyFilters(filters); //applies the filters to the component.
14
15await component.clearFilters(); // Clears the filters applied to the component.

1const metric = new AnalyticsMetric({
2  parentIdOrElement: "metric-container",
3  idOrApiName: "my-metric",
4});
5
6await metric.render();
7
8const timeRange: MetricTimeRange = {
9  operator: "PreviousYear",
10};
11
12await metric.applyTimeRange(timeRange);
13
14await metric.clearTimeRange(); // Clears the time range applied to the component.
15
16// Examples of valid time range filter formats:
17// { "operator": "Yesterday" }
18// { "operator": "LastNDays", values: [30] }
19// { "operator": "CurrentYearToDate" }
20// { "operator" : "Between" , "values" : ["2019-06-26","2023-07-07"] }
21// etc.

1// Assuming `myComponent` is an instance of a class that implements the export() method
2// Export with default filename and default PNG format
3await myComponent.export();
4
5// Export with a custom filename (still as PNG)
6await myComponent.export("my-component");
7
8// Export with custom filename and file type
9await myComponent.export("report", ExportFileType.PNG); // Currently only PNG supported

1// For metrics or visualizations, no need to pass dataSources, will return map for the single underlying data source:
2const fieldsMap = await component.getFields();
3
4// Example response structure:
5// fieldsMap => Map {
6//   "SalesData" => [
7//     { apiName: "Amount", label: "Amount", dataType: "Number", fieldType: "Measure" },
8//     { apiName: "Region", label: "Region", dataType: "Text", fieldType: "Dimension" }
9//   ]
10// }

1const fieldValues = await component.getFilterFieldValues("Account", "AccountObject", "Acme");
2console.log(fieldValues);
3
4// Example response:
5// [
6//   "Acme Corporation",
7//   "Acme Inc.",
8//   "Acme Solutions"
9// ]

1// For dashboards, the `dataSource` attribute is required in the filter input
2// to specify the data source to which the filter should be applied.
3
4await component.render();
5
6const filters: UnifiedFilterJson[] = [
7  {
8    fieldName: "Account.Name",
9    operator: FilterOperator.Equals,
10    values: ["Acme Corp"],
11    dataSource: "SalesData",
12  },
13];
14
15await component.applyFilters(filters); //applies the filters to the component.
16const appliedFilters = await component.getFilters(); // Returns the filters applied to the component.

1// For metrics or visualizations, no need to pass dataSource.
2
3await component.render();
4
5const filters: UnifiedFilterJson[] = [
6  {
7    fieldName: "Account.Name",
8    operator: FilterOperator.Equals,
9    values: ["Acme Corp"],
10  },
11];
12
13await component.applyFilters(filters); //applies the filters to the component.
14const appliedFilters = await component.getFilters(); // Returns the filters applied to the component.

1// Example response structure for metric or visualization:
2// {
3//   fields: Map {
4//     "SalesData" => [
5//       { apiName: "Amount", label: "Amount", dataType: "Number", fieldType: "Measure" },
6//       { apiName: "Region", label: "Region", dataType: "String", fieldType: "Dimension" }
7//     ]
8//   },
9//   filterFields: Map {
10//     "SalesData" => [
11//       { apiName: "Amount", label: "Amount", dataType: "Number", fieldType: "Measure" }
12//     ]
13//   }
14// }

1const metric = new AnalyticsMetric({
2  parentIdOrElement: "metric-container",
3  idOrApiName: "my-metric",
4});
5
6await metric.render();
7
8await metric.getLayout(); // Returns the layout of the component.
9
10// Example of MetricLayoutAttributes object returned:
11// {
12//    "componentVisibility": {
13//     "details": true,
14//     "title": true,
15//     "value": true,
16//     "comparison": true,
17//     "chart": true,
18//     "insights": true,
19//     "menu": true,
20//     "badge": true
21//    }
22//  }

1const metric = new AnalyticsMetric({
2  parentIdOrElement: "metric-container",
3  idOrApiName: "my-metric",
4});
5
6await metric.render();
7
8const timeRange: MetricTimeRange = {
9  operator: "PreviousYear",
10};
11
12await metric.applyTimeRange(timeRange);
13
14await metric.getTimeRange(); // Returns the time range applied to the component.
15
16// Examples of valid time range filter formats:
17// { "operator": "Yesterday" }
18// { "operator": "LastNDays", values: [30] }
19// { "operator": "CurrentYearToDate" }
20// { "operator" : "Between" , "values" : ["2019-06-26","2023-07-07"] }
21// etc.