Thursday, February 2, 2017

Salesforce Wave Explained - XMD 2.0 Migration

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.

XMD 1.1
"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"
   ]

8 comments:

  1. 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...

    ReplyDelete
  2. I 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.

    For 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]"
    }
    }
    ]

    ReplyDelete
  3. 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)

    ReplyDelete
  4. can you please explain derived dimensions and derived measures in 2.0

    ReplyDelete
    Replies
    1. The 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.

      Delete
    2. Hello, 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?

      Delete
    3. If you have multiple fields, the dimensions section would look like the following

      {
      "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"
      }
      ]
      }
      ]
      }

      Delete
    4. What about color for Measures? Where do those go?

      Delete