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 dashboard to an app.
  

Solve the Case of the Missing Dashboard

In this unit, you see how to add flavor to your template and the underlying functionality that spices up the app. You do that by adding a configuration wizard containing questions about how users want CRM Analytics to create the app. You don’t do any of this yourself here, as the purpose is to give you a taste of the power of templates. But this unit gives you a pretty good idea of how to get started with your templates.

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

Here are the steps to take:

1. Add the Service Performance dashboard to template-info.json along with an override that enables the template to add Cases to the app.
   
2. Add a rule to template-to-app-rules.json that tells the template to include Cases in the app.
   
3. Amend variables.json with a wizard question letting partners add Cases, if their org uses that object. (This question also determines whether the template adds the Service Performance dashboard to the app.)
   
4. Edit ui.json to add the question about Cases to the wizard.
   

Here’s 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…). 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 condition gives partners a choice: If their org uses the Cases object to track service engagements in Salesforce, they can add the object to the Execs Only app and get a Service Performance dashboard.

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

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

You 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. So, 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. Here’s what the new JSON does to your template:

1. Adds a wizard with one question, asking if the user wants to add data from the Cases object to the app. 
   

2. Tells CRM Analytics to add the new Cases dataset when it creates the app.
   
3. 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 you’re not done. Remember, the CEO asked you to add other options to the template. You do that next.

Same Dashboards, Different Data

DTC’s partners asked the CEO if they could choose how 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 track their customers' 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 partners 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? By editing the JSON files. If you read the last section carefully, you might have figured out which files to edit:

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

You don’t change template-info.json because you’re not adding any elements to the app—just changing some of the data it includes.

Here’s the code. Remember the other empty rules section of template-to-app-rules.json? To add questions about specific data to display in dashboards, you 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) that partners select to designate the sources of new business. In Execs Only, those values are items from the Lead Source field, such as Word of mouth, Public Relations, and so on. Action 2 sets the labels for the 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 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, those values are 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 your new actions point to variables (for example, Variables.Geography.fieldName) 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 defines 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 are 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 you’ve already seen.

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

Here's what the JSON you added does to your template:

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

2. Lets users choose the fields they use to segment geographies and track sources for new business.
   
3. Makes sure that data ends up in the right place in dashboards and datasets.
   

Thanks to a little JSON code, your template now gives partners choices over how they create their app. They can add the Service Performance dashboard and ensure the app’s dashboards reflect how 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 knock off her—and your partners’—socks. 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.