📖
PixieBrix Documentation
☑️

Creating an Autotracked Checklist

Introduction

Checklists are an essential tool for Process Excellence. They ensure best practices have been considered, even in uncommon or high stress situations

In this developer tutorial, we'll create a checklist for an agent using the Salesforce Service Console to ensure they've viewed the Details tab for the case.

For auditing purposes, we'll automatically track whether or not the agent has opened the tab

image

When developing auto-populating checklists, the basic approach we'll take is:

  1. Create a trigger starter brick for each kind of event we want to track (e.g., tab click)
  2. In the mod, use the trigger to run a @pixiebrix/state/set action to set a flag in the page state when the action is performed
  3. In the mod, use the @pixiebrix/form-modal action to display a checklist to the user, pre-filled based on the detected events

Event Triggers

In PixieBrix, the trigger starter brick is used to perform an action automatically in response to a DOM event.

For our checklist, we want to track which tabs the agent clicked on. So we'll use we'll use a click trigger installed on all the a[role="tab"] anchors for the active case:

apiVersion: v1
kind: extensionPoint
metadata:
  id: "@tutorial/salesforce/tab-trigger"
  version: 1.0.0
  name: Salesforce Case Tab Trigger
  description: Trigger event when a tab is clicked in the Salesforce case interface
definition:
  type: trigger
  trigger: click
  isAvailable:
    matchPatterns: "https://*.lightning.force.com/lightning/r/Case/*/view"
  rootSelector: '.oneWorkspace[aria-expanded="true"] a[role="tab"]'
  reader:
    # Grab information about the HTML element that was clicked
    - "@pixiebrix/html/element"
    # (Optional) additionally grab some context about the agent's session when the tab was clicked
    - "@pixiebrix/session"
    - "@pixiebrix/timestamp"

Tracking Events

With our trigger starter brick defined, we'll set up a mod to update the state with the triggered event using the @pixiebrix/state/set.

In our case, we defined a single starter brick that will work on all tabs. Therefore, our mod configuration needs to get a tab identifier to associate with the event. A simple way to do this is to use the @pixiebrix/jq brick to create a state update that we'll then merge into the page state with the @pixiebrix/state/set brick

⚠️
For the sake of simplicity, we're not accounting for an agent switching between cases. In Salesforce, all the cases are rendered on the same tab, so in practice you'd want to have store a separate checklist for each case number.

- id: "@tutorial/salesforce/tab-trigger"
  label: Tab trigger
  config:
	  action:
      # The jq brick is an easy way to construct JSON object with dynamic
      # key names.
			- id: "@pixiebrix/jq"
        outputKey: step
        config:
          # In Salesforce Service Console the tab identified is in the 
          # data-tabValue HTML attribute
					filter: "{ {{{ data.tabValue }}}: true }"
			- id: "@pixiebrix/state/set"
				config:
          # Merge in with the other steps that may have been clicked. 
          # Use "deep" so that it merges within the checklist subproperty
					mergeStrategy: deep
          data:
	          checklist: "@step"

When the user clicks the "Details" tab which has the data-tabValue="detailTab" atrribute, the state will become:

⚠️
In Salesforce, different tab bars use different data-* attributes to for the tab identifier. If you want to also track these, you'll need to either: 1) define additional triggers that use those attributes, or 2) modify the filter in the jq step above to use whichever data attribute is defined
{
  checklist: {
		detailTab: true
  }
}

Displaying the Checklist

To display the checklist (e.g., in response to a button click), we'll use the @pixiebrix/form-modal brick defining a field for each item in the checklist.

  1. Get the current state with @pixiebrix/state/get
  2. Create an object with keys for each step, even those that have not been completed yet
  3. Show the form, defaulting the field value to whether or not the step has been completed

action:
	- id: "@pixiebrix/state/get"
		outputKey: state
		config: {}
	- id: "@pixiebrix/jq"
		templateEngine: nunjucks
	  outputKey: detected
		config:
			# Create an object that contains all the keys with boolean values
      # Necessary since we have to pass boolean values for the defaults
      # to @pixiebrix/form-modal
			filter: |
				{ 
					detailTab: {{ "true" if @state.checklist.detailTab else "false" }}
				}
  - id: "@pixiebrix/form-modal"
		outputKey: form
		config:
			schema: 
				title: Case checklist
				type: object
				properties:
					DetailDone:
						type: boolean
						title: Verify the case details
						description: Verify details on the Details tab for the case
						# Default the checkbox whether or not the event has happened
            # Must be a boolean, so cannot use template strings
						default: "@detected.detailTab"
	          # Force the user to click the checkbox before submitting the form
					  enum: [true]

Twitter