Extended Metadata (XMD) Overview

Extended metadata (XMD) enables you to customize the formatting of dashboard elements in Wave Analytics.

If you modify the XMD for a dataset, every UI visualization that uses the dataset uses the new formatting. You can control the following:

The formatting of measures
Display labels for dimensions and measures
The grouping of dimensions of measures
Colors of specific fields
Default columns to be displayed for a values table
The hiding of dimensions and measures in the user interface
Custom menus that let users take advantage of actions on Salesforce objects and follow links to records in Salesforce and external websites
Mapping of Salesforce org IDs to their URLs so that a link to a Salesforce record from a multi-org dataset resolves to the correct org instance for that record

The XMD file is in JSON format. To access the XMD file, edit the corresponding dataset. You can download the existing XMD file from the Edit page.

Save XMD files in UTF-8 format to be sure that Wave visualizations display international characters.

Note

Refer to the XMD 2.0 section for information about XMD changes and updates.

Extended Metadata Example

The following example illustrates the format of the XMD file.

Every dimension and measure that’s referenced must be valid. Otherwise the reference is ignored.

Note

1{
2    "formats": {
3        "measures": {
4            "Amount": [
5                "$#,##0.00",
6                1
7            ]
8        }
9    },
10    "hide_dimensions": [
11         "Owner-Email"
12    ],
13    "labels": {
14        "dimensions": {
15            "CloseDate": "Close Date GMT",
16            "CloseDate_Day": "Close Date Day",
17            "CloseDate_Month": "Close Date Month",
18            "CloseDate_Quarter": "Close Date Quarter",
19            "CloseDate_Week": "Close Date Week",
20            "CloseDate_Year": "Close Date Year",
21            "CreatedDate": "Created Date GMT",
22            "CreatedDate_Day": "Created Date Day",
23            "CreatedDate_Month": "Created Date Month",
24            "CreatedDate_Quarter": "Created Date Quarter",
25            "CreatedDate_Week": "Created Date Week",
26            "CreatedDate_Year": "Created Date Year",
27            "Id": "Id",
28            "OpportunityId": "Opportunity Id",
29            "StageName": "Opp Stage"
30        },
31        "measures": {
32            "Amount": "Total Amount"
33        },
34        "keys": {
35            "IsClosed": {
36                "true": "Closed",
37                "false": "Open"
38            },
39            "Outcome": {
40                "true": "Won",
41                "false": "Lost"
42            },
43            "Region": {
44                "EU": "Europe",
45                "AP": "Asia Pacific",
46                "US": "United States"
47            }
48        }
49    },
50    "types": {
51        "Close Date GMT": {
52            "dims": {
53                "day": "CloseDate_Day",
54                "fullField": "CloseDate",
55                "month": "CloseDate_Month",
56                "quarter": "CloseDate_Quarter",
57                "week": "CloseDate_Week",
58                "year": "CloseDate_Year"
59            },
60            "meas": {
61                "epoch_day": "CloseDate_day_epoch",
62                "epoch_second": "CloseDate_sec_epoch"
63            },
64            "type": "date"
65        },
66        "Created Date GMT": {
67            "dims": {
68                "day": "CreatedDate_Day",
69                "fullField": "CreatedDate",
70                "month": "CreatedDate_Month",
71                "quarter": "CreatedDate_Quarter",
72                "week": "CreatedDate_Week",
73                "year": "CreatedDate_Year"
74            },
75            "meas": {
76                "epoch_day": "CreatedDate_day_epoch",
77                "epoch_second": "CreatedDate_sec_epoch"
78            },
79            "type": "date"
80        }
81    },
82    "colors": {
83        "StageName": {
84            "5 - Closed-Won": "#4f4",
85		          "5 - Closed-Lost": "#f44"
86	  },
87	  "Region": {
88	      "AP": "#fc6",
89	     	"EU": "#48f",
90		     "US": "#f88"
91	  }
92    },
93    "values_query_columns": [
94        "Id",
95        "OpportunityId",
96        "StageName"
97      ]
98}

XMD 2.0

Some XMD elements have changed, as have some behaviors. In Salesforce development circles these changes are referred to as XMD 2.0, versus XMD 1.1.

Behind the scenes, a key change is that XMD is now stored in BPOs (Base Platform Objects) rather than in JSON files. The API works on these objects, so you can use the XMD API endpoints to manipulate your XMD directly.

From the user perspective, you still download and upload JSON files to effect your changes—the XMD is converted on-the-fly. However, there are some side effects of this change:

XMD is stored for each dataset version.
system XMD is generated when main.json is uploaded, or when a GET call is made via the API on an old-version dataflow.

As before, main type XMD is created by merging system and user. Modify the user XMD file to customize the formatting of many dashboard elements in Wave Analytics.

If dataset metadata is changed—like a particular column is deleted or renamed as a result of changes to the dataflow—the associated user XMD must also be updated, so it doesn’t continue to reference the changed column and cause validation to fail. Once the XMD has been updated, it must be reloaded (i.e. downloaded then uploaded) in order to pass validation. This must be done even if the changes to the dataflow are reverted.

Warning

What Does This Mean To Me?

This table describes changes to XMD elements. While most of these changes are new elements, several are existing elements that are renamed. Please update your XMD if you use these elements.

Element	Next-level element	Next-level element	Type	Note
dimensions
	sfdcActions		List	Renamed to salesforceActions. The user interface still uses XMD 1.1, while the API uses XMD 2.0. Only use the renamed element name if using XMD 2.0. The new enabled flag in the salesforceActions list is a placeholder in XMD 2.0, reserved for future use. Note
	sfdcActionsEnabled		Boolean	Renamed to salesforceActionsEnabled. The user interface still uses XMD 1.1, while the API uses XMD 2.0. Only use the renamed element name if using XMD 2.0. Note
measures
	format		List	Existing.
		unitMultiplier	Double	New. The multiplier for the unit.
		customFormat	String	Retained for combatibility. Specify a format string, for example, `"[\"\",1]"`
dates	label		String	New. Label of the Date column.
	fiscalMonthOffset		Integer	New. Offset number of months for the fiscal year in relation to the calendar year.
	firstDayOfWeek		Integer	New. What to use as the first day of the week.

Wave Analytics Extended Metadata (XMD) Reference

Extended Metadata (XMD) Overview

Extended Metadata Example

XMD 2.0