Make Your Template Smarter by Adding a Wizard

Learning Objectives

After completing this unit, you’ll be able to:

Understand how to add a wizard question to a template.
Explain how adding the wizard question and making other changes to template files can add a new dashboard to an app.

Solve the Case of the Missing Dashboard

In this unit, we show how to add flavor to our template and the underlying functionality that spices up the app. We’ll do that by adding a configuration wizard to the app with a set of questions about how users wants CRM Analytics to create the app. You won’t do any of this yourself since our purpose is to give you a taste of the power of templates. But we give you a pretty good idea of how to get started with your own templates.

Let’s start with the code to add the Service Performance dashboard. Remember the original template doesn’t create it. Why not? First, because the dashboard is not referred to in the JSON files. There’s another reason. The dashboard runs on data from the Salesforce Cases object—which DTC Customer Service uses to track engagements. Our original template doesn’t add Cases data to the app, so there’s no data in the app to populate the dashboard. We have to add logic to add Cases.

Here are the steps we have to take:

Add the Service Performance to template-info.json along with an override that enables the addition of Cases to the app.
Add a rule to rules.json that tells the template to include Cases in the app.
Amend variables.json with a wizard question letting partners add Cases, if their org uses that object. (This will also depend on whether they want to add the Service Performance dashboard to the app.)
Edit ui.json to add the question about Cases to the wizard.

Let’s look at the code for each of these changes. First, here’s the dashboards section of the original version of template-info.json with two dashboard references. The references point to the JSON files for the basic app’s two dashboards, Exec_Overview_Pipeline_Performance.json and Exec_Overview_Sales_Performance.json:

"dashboards" : [ {
    "file" : "dashboard/Exec_Overview_Pipeline_Performance.json",
    "name" : "Exec_Overview_Pipeline_Performance_PartOne",
    "label" : "Exec Overview - Pipeline Performance"
  }, {
    "file" : "dashboard/Exec_Overview_Sales_Performance.json",
    "name" : "Exec_Overview_Sales_Performance_PartOne",
    "label" : "Exec Overview - Sales Performance"
  } ],

And here’s the edited version, with a third dashboard reference—to Exec_Overview_Service_Performance.json and an override referring to Cases data:

"dashboards" : [ {
    "file" : "dashboard/Exec_Overview_Pipeline_Performance.json",
    "name" : "Exec_Overview_Pipeline_Performance",
    "label" : "Exec Overview - Pipeline Performance"
  }, {
    "file" : "dashboard/Exec_Overview_Sales_Performance.json",
    "name" : "Exec_Overview_Sales_Performance",
    "label" : "Exec Overview - Sales Performance"
  }, {
    "condition" : "${Constants.HasCases || Variables.Overrides.createAllDashboards}",
    "file" : "dashboard/Exec_Overview_Service_Performance.json",
    "name" : "Exec_Overview_Service_Performance",
    "label" : "Exec Overview - Service Performance"
  } ],

You add conditional statements to template-info.json that tell the app to include a dashboard or dataset based on a given variable. In this case, the condition determines whether the user adds the Cases object to the app ( Constants.HasCases || Variables.Overrides…). What that means is that when a user creates the app, CRM Analytics looks for a constant called HasCases. If it’s there, it adds the Service Performance dashboard. If not, it leaves the dashboard out. This gives partners a choice: If their org uses the Cases object to track services engagements in Salesforce, they can add the object to the Execs Only app and they’ll get a Service Performance dashboard. If they don’t, they can leave it out.

Where does the HasCases constant come from? Maybe you remember that rules.json has a constants section with nothing in it:

{
  "constants": [],
  "rules": []
}

Remember: we refer to the template-to-app-rules.json file using the short-hand rules.json to make these instructions easier to read.

We add a constant called HasCases that tells CRM Analytics to include the Cases sObject based on the variable Variables.SObjectChoices.

  "constants": [
    {
      "name": "HasCases",
      "value": "${array:contains(Variables.SObjectChoices, 'Cases')}"
    }
  ]

And where does CRM Analytics look for that variable? You guessed it: variables.json. We add an SObjectChoices variable:

"SObjectChoices": {
    "label": "Choose additional objects to include in your app. Selecting Cases will add the Service Performance dashboard and a Cases dataset",
    "description": "You can analyze data and build out additional dashboards using data from the additional object.",
    "defaultValue": [],
    "required": false,
    "variableType": {
      "type": "ArrayType",
      "itemsType": {
        "enums": [
	      "Cases"
        ],
        "type": "StringType"
      }
    }
  },

You can see the text for the wizard question in : Choose additional objects to include in your app. You can also see “Cases” as an enum under “itemsType”.

Finally, here’s the JSON from ui.json telling the wizard to display a question reflecting the new SObjectChoices variable:

  "pages": [
    {
      "title": "Create Execs Only App",
      "variables": [
        { "name": "SObjectChoices" }
      ]
    },

If you remember, the original ui.json file was empty.

A Wizard Is Born

And that’s it. Let’s review what the new JSON does to our template:

Adds a wizard with a single question, asking if the user wants to add data from the Cases object to the app.
Tells CRM Analytics to add the new Cases dataset to the app when it’s created.
Tells CRM Analytics to create a Service Performance dashboard using data from Cases.

Pretty cool—a small amount of simple code leads to a powerful result. But we’re not done. Remember, the CEO asked us to add some other options to the template. We do that next.

Same Dashboards, Different Data

DTC’s partners asked the CEO if they could choose the way the Execs Only dashboards surfaced data about geography and sources of new business. DTC’s version shows geographic data according to the Accounts object Billing Country field. That’s the primary field DTC uses to keep track of their customer’s locations. App dashboards show new business according to the Lead Source field in the Opportunities object—again, the field DTC reps use to indicate potential new business.

How do you give them control over the data they look at in their version of Execs Only? By adding questions to the wizard. And how do you do that? You’re probably way ahead of us—by editing the JSON files. If you read the last section carefully, you might have figure out which files to edit:

rules.json, where you’ll define what the dashboards do with the data from fields selected in the wizard.
variables.json, where you add the wizard questions and specify the values your partners can select when they answer the questions.
ui.json, where you’ll determine the order in which the wizard displays the questions.

We don’t change template-info.json because we’re not adding any elements to the app—just changing some of the data that’s included in it.

Again, let’s take a look at the code. Remember the other empty section of rules.json, that is rules. To add questions about specific data to display in dashboards, we add two rules to that section. Here’s the top of the file with the first rule, ReplaceDashboardVariables:

  "rules": [
    {
      "name": "ReplaceDashboardVariables",
      "appliesTo": [
        {
          "type": "dashboard",
          "name": "*"
        }
      ],
      "actions": [
        {
          //1-THIS ACTION SETS NEW BUSINESS SOURCE FIELD NAME
          "action": "set",
          "description": "Replace LeadSource Dimension",
          "path": "$..*",
          "value": "${string:replace(Rules.CurrentNode,\"LeadSource\", Variables.Source_L2.fieldName)}"
        },
        {
          //2-THIS ACTION SETS LABEL FOR FILTER WITH NEW BUSINESS SOURCE DATA
          "action": "set",
          "description": "Replace LeadSource Dimension",
          "path": "$..*",
          "value": "${string:replace(Rules.CurrentNode,\"Lead Source\", Variables.Source_L2.fieldLabel)}"
        },
        {
          //3-THIS ACTION SETS GEOGRAPHY FIELD NAME
          "action": "set",
          "description": "Replace Geography Dimension",
          "path": "$..*",
          "value": "${string:replace(Rules.CurrentNode,\"BillingCountry\", Variables.Geography.fieldName)}"
        },
        {
         //4-THIS ACTION SETS LABEL FOR FILTER WITH GEOGRAPHY DATA
          "action": "set",
          "description": "Replace Geography Dimension",
          "path": "$..*",
          "value": "${string:replace(Rules.CurrentNode,\"Billing Country\", Variables.Geography.fieldLabel)}"
        }
      ]
    },

The ReplaceDashboardVariables rule replaces the label and name of the default dimension in dashboards if the user selects a value other than Lead Source from the wizard. Rules define several set actions. In this case, the actions set a value in dashboards. Action 1 sets the field name (fieldName) partners select to designate the sources of new business. As you saw before, in Execs Only that’s items from the Lead Source field, such as Word of mouth, Public Relations, and so on. Action 2 sets the labels of filters that contain data from that field (fieldLabel).

Here’s the Lead Source chart from the Pipeline Performance dashboard. It shows the label Lead Source (1) and the items that come from the Lead Source field (2). Partners want to be able to choose a different field to use as the source of new business. The field they choose—say New Business—replaces Lead Source, and the values from the New Business field replace Employee Ref, Public Relations, and so on.

Actions 3 and 4 do the same for geographic data. In Execs Only, that’s items from the Billing Country field (the country names Canada, USA, and so on) and the label Billing Country.

Here’s the second rule ReplaceWorkflowVariables, which applies to the dataflow file. (Workflow refers to the dataflow for the app.) Action 5 replaces new business source data in the dataflow. Action 6 does the same thing for geographic data.

{
      "name": "ReplaceWorkflowVariables",
      "appliesTo": [
        {
          "type": "workflow",
          "name": "*"
        }
      ],
      "actions": [
        {
          //5-THIS ACTION CHANGES NEW BUSINESS SOURCE DATA IN THE DATAFLOW
          "action": "set",
          "description": "Replace LeadSource Dimension",
          "path": "$..*",
          "value": "${string:replace(Rules.CurrentNode,\"LeadSource\", Variables.Source_L2.fieldName)}"
        },
        {
          //6-THIS ACTION CHANGES GEOGRAPHIC DATA IN THE DATAFLOW
          "action": "set",
          "description": "Replace BillingCountry Dimension",
          "path": "$..*",
          "value": "${string:replace(Rules.CurrentNode,\"BillingCountry\", Variables.Geography.fieldName)}"
        }
      ]
    },

All our new actions point to variables (for example, Variables.Geography.fieldName), which are defined in variables.json.

   //1-VARIABLE FOR GEOGRAPHIC DATA
  "Geography": {
    "label": "What field do you want to use to segment customers by geography?",
    "description": "Choose how Execs Only filters geographic data.",
    "defaultValue": {
      "sobjectName": "Account",
      "fieldName": "BillingCountry"
    },
    "required": true,
    "excludeSelected": true,
    "excludes": [
      "Name",
      "Industry"
    ],
    "variableType": {
      "type": "SobjectFieldType",
      "dataType": "xsd:string"
    }
  },
  //2-VARIABLE FOR SOURCES OF NEW BUSINESS
  "Source_L2": {
    "label": "What field do you want to use to segment sources for new business?",
    "description": "Choose how Execs Only filters data about new business sources.",
    "defaultValue": {
      "sobjectName": "Opportunity",
      "fieldName": "LeadSource"
    },
    "required": true,
    "excludeSelected": true,
    "excludes": [
      "Name",
      "StageName",
      "ForecastCategory",
      "ForecastCategoryName"
    ],
    "variableType": {
      "type": "SobjectFieldType",
      "dataType": "xsd:string"
    }
  },
  //3-ORIGINAL VARIABLE FROM PREVIOUS VERSION OF FILE
  "Overrides": {
    "required": true,
    "description": "Internal configuration to allow asset creation overrides, not to be displayed in UI.",
    "defaultValue": {
      "createAllDashboards": false
    },
    "variableType": {
      "type": "ObjectType",
      "properties": {
        "createAllDashboards": {
          "type": "BooleanType"
        }
      },
      "strictValidation": true
    }
  },

Variable 1 shows both a wizard question about geographic data and a description to help partners select an answer. It also specifies which sObject contains the values in the partner's org that will be valid answers in the wizard. The template uses the answer to create a customized dashboard experience. Variable 2 does the same thing for a wizard question about sources of new business. Variable 3 is the original override, which we’ve already discussed.

Finally, here’s the code from ui.json that determines how the new wizard orders questions. Note that it also includes the question about adding Cases to the Execs Only app (SObjectChoices).

  "pages": [
    {
      "title": "Create Execs Only App",
      "variables": [
        { "name": "Geography" }, //QUESTION ABOUT GEOGRAPHIC DATA
        { "name": "Source_L2" }, //QUESTION ABOUT SOURCES OF NEW BUSINESS
        { "name": "SObjectChoices" } //QUESTION ABOUT ADDING CASES DATA
      ]
    }

Making the Wizard Even Wiser

Let’s review what the JSON we added does to our template:

Makes the wizard “smarter” with a couple more questions. Users can now answer questions about geography and new business sources in addition to the question about Cases data.
Lets users choose the fields they use to segment geographies and track sources for new business.
Makes sure that data ends up in the right place in dashboards and datasets.

Thanks to a little JSON code, our template now gives partners choice over how they create their app. They can add the Service Performance dashboard. They can also make sure the app’s dashboards reflect the way they store (and like to view) data.

You’re excited to show it to the CEO—you know she’ll be excited, too. But as you’ve worked along with the JSON, you’ve had a couple of ideas you think will really knock her—and your partners’—socks off. You decide to give those ideas a try before going to the CEO.

Before enhancing your template even further, keep working on your CRM Analytics Templates badge by answering the questions at the bottom of the page,

Resources

CRM Analytics Templates Developer Guide, Step 3: Edit the JSON Files.