The Winter 17 Salesforce release included a new format for Extended Metadata (XMD), which is used to customize the formatting of dashboard elements in Wave Analytics. The pre-Winter 17 version is known as XMD 1.1, while the new format is XMD 2.0.
In addition to the format change, XMD became a Base Platform Object, rather than a JSON file on the dataset. You still use JSON to specify and upload the XMD. As a Base Platform Object, you can manipulate JSON through APIs, such as the REST API through workbench. It also means the XMD format and contents are validated, allowing only correct JSON files to be uploaded.
While there is an XMD Overview and Reference guide in the developer documentation, some of the examples still retained the 1.1 format. There is also a help document that discusses the transition from 1.1 to 2.0, which give before and after pseudo code.
What I did not find were before (1.1) and after (2.0) examples for transforming each section of an existing XMD 1.1 file. Here is my outline for turning XMD 1.1 into XMD 2.0, section by section, with before and after examples.
Dimensions
The dimension section has changed, with many of the previously separate elements becoming embedded within Dimensions (more on those below). Within the dimensions section, several key changes have been made.
- field
- Identifies the field in a dimension
- recordIdField
- Identifies the Id field used to open the record in Salesforce or use in actions
- recordDisplayFields
- Is a list parameter of fields for a dimension
- sfdcActionsEnabled
- Becomes salesforceActionsEnabled
- sfdcActions
- Becomes the salesforceActions list parameter
- linkTemplateEnabled
- Is a boolean parameter for a dimension
- linkTemplate
- Is a string parameter for a dimension
- linkTooltip
- Is a string parmeter for a dimension
XMD 1.1
"dimensions": [
{
"linkTemplateEnabled": true,
"linkTemplate": "http://www.google.com/search?q={{row. Tenant_Name__c}}",
"linkTooltip": "Search Google"
"field": "Tenant_Name__c",
"sfdcActionsEnabled": false
},
{
"recordDisplayFields": [],
"linkTemplateEnabled": true,
"field": "Name",
"sfdcActionsEnabled": true,
"sfdcActions": [
{
"name": "ActionAPIName"
}
],
"recordIdField": "Id",
"recordDisplayFields": [
"Name",
"Tenant_Name__c"
]
}
]
XMD 2.0
"dimensions": [
{
"field": "Tenant_Name__c",
"label": "Tenant Name",
"salesforceActionsEnabled": false,
"linkTemplateEnabled": true,
"linkTemplate": "http://www.google.com/search?q={{row. Tenant_Name__c}}",
"linkTooltip": "Search Google"
},
{
"field": "Name",
"label": "Reporting Classification Number",
"salesforceActionsEnabled": true,
"salesforceActions": [
{
"name": "ActionAPIName"
}
],
"recordIdField": "Id",
"recordDisplayFields": [
"Name",
"Tenant_Name__c"
]
}
]
Formats
For format sections, the details for each measure moves into the measures section for that field.XMD 1.1
"formats": {
"measures": {
"Asset_Square_Feet__c": [
"#,###",
1
]
}
}
XMD 2.0
"measures": [
{
"field": "Asset_Square_Feet__c",
"format": {
"customFormat": "[\"#,###\",1]"
}
}
]
Hide Dimensions
For dimensions that should be hidden in Wave, set the showInExplorer for the field in the dimension section.
XMD 1.1
"hide_dimensions": [ "Asset_Risk__c" ]
XMD 2.0
"dimensions": [
{
"field": "Asset_Risk__c",
"showInExplorer": false
}
]
Hide Measures
For measures that should be hidden in Wave, set the showInExplorer for the field in the measure section.
XMD 1.1
"hide_measures": [ "Bedrooms__c" ]
XMD 2.0
"measures": [
{
"field": "Bedrooms__c",
"showInExplorer": false
}
]
Labels
There are several elements within labels that have new homes - dimensions, measures and keys. The labels for dimensions and measures move to each respective section.
Keys become embedded in the members parameters group for dimensions.
XMD 1.1
"labels": {
"dimensions": {
"Custom_Field__c" : "My Field"
},
"measures": {
"Custom_Measure__c" : "My Measure"
},
"keys": {
"Custom_Field__c": {
"true": "Closed",
"false": "Open"
}
}
}
XMD 2.0
"dimensions": [
{
"field": "Custom_Field__c",
"label": "My Field",
"members": [
{
"member": "true",
"label": "Closed"
},
{
"member": "false",
"label": "Open"
}
]
}
],
"measures": [
{
"field": "Custom_Measure__c",
"label": "My Measure"
}
]
Colors
Colors used to set the how certain visualization elements are displayed. Similar to keys, the move into the members section of a dimension.
"colors": {
"Custom_Field__c": {
"true": "#00FF00",
"false": "#FF0000"
}
}
XMD 2.0
"dimensions": [
{
"field": "Custom_Field__c",
"label": "My Field",
"members": [
{
"member": "true",
"label": "Closed",
"color": "#00FF00"
},
{
"member": "false",
"label": "Open"
"color": "#FF0000"
}
]
}
]
Types
Types are used to define dates. Now it goes in the dates section as fields.
XMD 1.1
"types": {
"Valuation Date": {
"dims": {
"week": "Valuation_Date__c_Week",
"hour": "Valuation_Date__c_Hour",
"month": "Valuation_Date__c_Month",
"year": "Valuation_Date__c_Year",
"day": "Valuation_Date__c_Day",
"fullField": "Valuation_Date__c",
"minute": "Valuation_Date__c_Minute",
"quarter": "Valuation_Date__c_Quarter",
"second": "Valuation_Date__c_Second"
},
"meas": {
"epoch_second": "Valuation_Date__c_sec_epoch",
"epoch_day": "Valuation_Date__c_day_epoch"
},
"type": "date"
}
}
XMD 2.0
"dates": [
{
"label": "Valuation Date",
"showInExplorer": true,
"fiscalMonthOffset": 0,
"isYearEndFiscalYear": true,
"firstDayOfWeek": 0,
"fields": {
"fullField": "Valuation_Date__c",
"year": "Valuation_Date__c_Year",
"quarter": "Valuation_Date__c_Quarter",
"month": "Valuation_Date__c_Month",
"week": "Valuation_Date__c_Week",
"day": "Valuation_Date__c_Day",
"hour": "Valuation_Date__c_Hour",
"minute": "Valuation_Date__c_Minute",
"second": "Valuation_Date__c_Second",
"epochSecond": "Valuation_Date__c_sec_epoch",
"epochDay": "Valuation_Date__c_day_epoch"
},
"compact": true
}
]
Values Query Column
Used to show a certain set of columns in the values table by default, this section switches to showDetailsDefaultFields. No need to move around the data for this one, just change the name.
XMD 1.1
"values_query_columns": [
"Period__c",
"Portfolio_Name__c",
"Property_Name__c",
"Property_Location_State__c",
"Asset_Year_Built__c"
]
XMD 2.0
"showDetailsDefaultFields": [
"Period__c",
"Portfolio_Name__c",
"Property_Name__c",
"Property_Location_State__c",
"Asset_Year_Built__c"
]
Nice update Carl. The documentation here is extremely lacking. It's a tedious trial and error to see what works. Do you have any more examples of measure formatting? I'm trying the new items like "prefix" and "unitMultiplier" but having no luck...
ReplyDeleteI have not seen the prefix and unitMultipler work for me either. I believe these will be used in some future functionality (but I don't have any official documentation to point to.
ReplyDeleteFor now, we can use the customFormat to apply prefix and unit multipliers. In the example below, I use a dollar sign in front of the format as well as two decimal places to display results as $145.00
In addition, a unit multiplier of 100 is used and will be applied when the values are displayed.
"measures": [
{
"field": "Asset_Amount__c",
"format": {
"customFormat": "[\"$#,###.00\",100]"
}
}
]
this broke so many data flows and data sets and Salesforce left us high and dry to figure it out ourselves. the OOTB sales app doesnt work anymore and we've extended those data sets so i can just uninstall and re-install them. tons of work here... i thought SFDC updates arent supposed to break previous functionality? anyone else dealing with this horrible upgrade (that salesforce should have built a migration tool for)
ReplyDeletecan you please explain derived dimensions and derived measures in 2.0
ReplyDeleteThe quick response is derived dimensions and measures are used to format fields you compute in expression such as SAQL that do not appear in the dataset. I will write up a post on using derived measures.
DeleteHello, running into an issue with adding labels to picklist values. It seems that only the last "field" that has labels is being respected within the "dimensions block. How would the XMD be written if you had multiple fields/picklist values you wanted to change the label for?
DeleteIf you have multiple fields, the dimensions section would look like the following
Delete{
"dimensions": [
{
"field": "Custom_Field__c",
"label": "My Field",
"members": [
{
"member": "true",
"label": "Closed"
},
{
"member": "false",
"label": "Open"
}
]
},
{
"field": "Custom_Field2__c",
"label": "My Field2",
"members": [
{
"member": "t",
"label": "Yes"
},
{
"member": "f",
"label": "No"
}
]
}
]
}
What about color for Measures? Where do those go?
Delete