Get started with advanced formatting in ArcGIS Dashboards

As high winds and dry conditions are an ongoing problem in the state of California, state utility officials constantly monitor power outages. The California Governor's Office of Emergency Services (Cal OES) tracks outages and publishes them to a web service that indicates the likely cause of the failure and the number of customers that are impacted by the event. To enable better decision-making and prioritization of resources, it is vital that the dashboards used by utility officials are configured to not simply display reported outages, but also to generate alerts and identify affected communities and impacted customers.

Using ArcGIS Dashboards, you will create a visually informative dashboard to view outages. Using advanced formatting in Arcade, you will be able to calculate the amount of time an outage has been active and add that information to the list of reported outages. Additionally, you will configure an alert that displays when a new outage has been reported.

This tutorial was last tested on February 28, 2024.

View final result

Requirements

• ArcGIS organizational account with a Publisher, Facilitator, or Administrator role in an ArcGIS organization (see options for software access)
• ArcGIS Dashboards

Create a power outage map

The first step is to create the map that will serve as the geographic focus of the dashboard. You will create a web map in ArcGIS Online with Map Viewer and add the power outage layer. You will then style the layer and its pop-ups. This web map and its layers will be the data source for your other dashboard elements.

Add layers to a new map

First, you’ll create the map for your dashboard in ArcGIS Online.

1. Sign in to your ArcGIS organizational account.
2. At the top of the page, click Map to open a new map.

   

   Note:

   Depending on your organizational and user settings, you may have opened Map Viewer Classic. ArcGIS Online offers two map viewers for viewing, using, and creating maps. For more information on the map viewers available and which to use, please see this FAQ.

   This tutorial uses Map Viewer.

   
3. On the Contents (dark) toolbar, click Add and choose Add layer from URL.

   

4. In the Layer details section, copy and paste the following web service into the URL field:

   https://services.arcgis.com/BLN4oKB0N1YSgvY8/arcgis/rest/services/Power_Outages_(View)/FeatureServer/0

   Note:

   This layer is the California Governor's Office of Emergency Services (Cal OES) Tracked Power Outage information for the state. Questions about this dataset may be directed to: [e-mail].

   The power outages in this layer are pulled directly from the utility public power outage maps, and the layer is automatically updated every 15 minutes. The following utility companies are included: Pacific Gas and Electric, Southern California Edison, San Diego Gas & Electric, Sacramento Municipal Utility District (SMUD), and Los Angeles Department of Water and Power (LADWP).

   Layers included in this dataset:

   • Power Outage Incidents—Point layer that shows data from all the utilities and is best for showing a general location of the outage and driving any numbers in dashboards.
   • Power Outage Areas—Polygon layer that shows the approximate geographic extent of the power outage.
   • Power Outages by County—This layer summaries the total impacted customers by county. This layer is useful for showing the impact of outages at the state level.

5. Click Add to map.

   The map now displays power outages in California. Since the data is updated frequently, you will set a refresh interval for the layer.

6. In the Refresh interval section of the Properties pane, turn on the Automatically refresh layer toggle.
7. Type 15 for the number of minutes.

   

   This matches the interval at which the layer is updated.

8. On the Contents toolbar, click Basemap.
9. In the Basemap pane, choose Streets (Night).

   

Style the layer

A utility outage represents an event; either scheduled, or the result of a failure, that causes a disruption of service to customers. Outage locations are typically reported by remote devices designed to detect system faults. By default, the incidents on the map are classified as planned and not planned. This is a good way to classify the data, but the layer can be styled to better distinguish the two.

1. On the Contents toolbar, click Layers.

   

2. In the Layers pane, click the Power Outages (View) - Power Outage Incidents layer.
3. On the Settings (light) toolbar, click Styles.

   

4. In the Styles pane, click Style options for the Types (unique symbols) style.

   

5. Under Outage Type, click the symbol for Not Planned.

   

6. In the Symbol style, under Current symbol, click Basic point.
   
7. Under Change symbol, from the Category drop-down menu, choose Firefly. Select a red color and click Done.

   

8. Click the symbol for Planned and choose a green Firefly symbol and click OK.

   

9. In the Styles options, click Done to finish styling your layer and then click Done to close the Styles pane.

   Now that the two outage types have been symbolized more distinctly, you will apply clustering to visualize concentrations of outages.

10. In the Settings (light) toolbar, click Aggregation.

    

11. In the Aggregation pane, turn on Enable aggregation.

    

    Clustering is enabled by default.

12. For Clustering, click on Options.

    

    The Clustering pane appears.

13. In the Clustering pane, for Cluster radius, drag the slider closer to Low. For Size range, drag the right slider to the left.

    

    The power plants layer is now symbolized with clusters. As you zoom in and out, the clusters are reconfigured to adapt to the current scale. Each cluster is labeled with the number of power plants it represents.

    You'll now choose a different basemap so the power plant features stand out better on the map. Since the points in this layer are represented with bright symbols, you can create contrast by putting them against a dark and neutral basemap.

14. Click back and close the Aggregation pane.

    

15. The Power Outages (View) – Power Outage Incidents layer style updates.

    

Configure pop-ups

Pop-ups are useful for summarizing a given data point on the map. By default, most pop-ups show all data fields and values. As a utility officer, however, you’re only interested in seeing the cause of the outage, the estimated fix time, and the associated utility company. Configuring the layer’s pop-ups allows you to tailor the information you see.

1. In the Layers pane, ensure the Power Outages (View) - Power Outage Incidents layer is selected, and on the Settings toolbar, select Pop-ups.
   

   The Pop-ups pane appears.

2. In the Pop-ups pane, click Title, and type Power Outage: {IncidentId}.

   

3. Click the Options button for the Fields list and choose Delete.

   

4. Click Add content and choose Text.

   The text editor appears. In the editor, you can use a combination of static text, and attribute fields to create a custom pop-up.

5. In the editor, type { and choose Impacted Customers.

   

   The field {ImpactedCustomers} adds to the text field.

6. After {ImpactedCustomers}, type a space followed by the following text:

   customers impacted. Power is expected to resume {EstimatedRestoreDate}.

   Cause: {Cause}

   Contact {UtilityCompany} for more details.

   

7. Click OK to save and close the editor.
8. On the map, zoom in to see individual outages.
9. Click an outage on your map to view the pop-up.

   If you click a cluster, you will see the default pop-up for the cluster.

   

10. On the Contents toolbar, click Save and open and choose Save as.

    

    The Save map window appears.

11. In the Save map window, for Title, type California power outages map and add your initials to make the map name unique within your organization.
12. For Tags, type California, power, outages.
13. For Summary, type A map of California power outages to be used in a dashboard.

14. Click Save.

Create a power outage dashboard

Using ArcGIS Dashboards, you can create a dashboard that allows users to quickly see power outages and the relevant information about them. Dashboards offers many configuration options to visualize data. With advanced formatting, you can derive and visualize data that is not available in the feature layer. The first piece of information you will derive is the outage duration, which represents the total time in hours and minutes of each outage event from the reported time to the current time. The second piece of information you will derive is the Reliability Impact Index (commonly referred to as SAIDI, the System Average Interruption Duration Index), which represents the total number of customers impacted divided by the outage duration in minutes.

Create the dashboard

1. If necessary, open the California power outages map web map.
2. On the Contents toolbar, click the Create app button and choose Dashboards.

   

   ArcGIS Dashboards opens in a new tab.

   The Title and Tag are already filled out based on your web map's item details.

3. For Summary, type This dashboard displays the current planned and unplanned power outages in the State of California.
4. Click Create dashboard.

   ArcGIS Dashboards opens a newly created dashboard with the California power outages map element. You will make the theme of the dashboard dark to match the basemap.

5. On the dashboard toolbar, click the Theme button.

   

   The Layout pane appears.

6. Under Layout, for Theme, click Dark.

Next, you will configure a list element using colors chosen to be seen on a dark background.

Configure the list element

The first element you will add to your dashboard is a list. A list is useful for showing features, in this case, outages. Using some advanced formatting, you can configure the list to display derived information about an outage.

1. On the dashboard toolbar, click Add element.

   

2. On the map element, click the left add button and choose List.

   

3. In the Select a layer window, click Power Outages (View) - Power Outage Incidents.
4. On the Data tab, in the Sort by section, click Add field and choose Start Date/Time.

   

5. Click Sort descending.

   

   Your list sorts to show the most recent outages at the top.

6. Click the List tab.

   The list shows the OBJECTID field for each data point. The OBJECTID, however, doesn't tell you anything about the outage. While some information is already available in the data, the outage duration and reliability index are not. You can calculate this using an Arcade expression. Arcade is a flexible expression language that allows you to work with data in real time in ArcGIS. You can use Arcade to perform field calculations on your data and customize how your data points render. You can build and apply Arcade expressions using the Arcade expression editor.

7. In the List options, click Enable next to Advanced formatting.

   

   The Arcade editor appears.

   Note:

   Once advanced formatting is enabled, system-defined properties are made unavailable. All formatting of the list visualization is done through the expression.

   The Expression section is where you build the expression. The Profile variables and Functions tabs are where you find the elements you will use in the expression. The Profile variables tab includes a list of predefined variables to assist with building expressions. For example, $datapoint gives you access to the fields in your data. The Functions tab is where you access the library of Arcade functions. You can click the information button next to each function to see the function's help on parameters, syntax, and usage. Using an Arcade expression, you will calculate the time elapsed between when the report was added and the current time. To do so, you will create a variable for the time the outage was reported, one for the current time, and use a built-in Arcade function to calculate the difference.

8. Click the Pop out editor button.

   

   The Advanced formatting window appears.

9. In the text box, delete the current expression and type var dateOpened =.
10. Place your cursor after the equals sign, add a space, and click the Profile variables tab.

    

11. Click the arrow for $datapoint.
12. In the list of variables that appear, click the $datapoint.StartDate variable.

    The variable adds to your line of code. This line defines the StartDate value as the time the outage was reported.

    

13. Click after StartDate and press Enter to start a new line.

    On the next line, you will define the second variable, which is the current time.

14. Type var currentTime =.
15. Click the Functions tab, in the search bar, type now. In the list of results, choose the Now() function.

    

    This adds the function to your expression. The Now() function returns the current date and time.

    

    Next, you will use the two defined variables to calculate the time elapsed using the DateDiff function. The DateDiff function subtracts two dates and returns the difference in the specified units. For this calculation, you will return the time in minutes.

16. Start a new line and type var minutesOpened = DateDiff(currentTime, dateOpened, 'minutes');

    The complete Arcade code is as follows:

    var dateOpened = $datapoint.StartDate
    var currentTime = Now()
    var minutesOpened = DateDiff(currentTime, dateOpened, 'minutes');

    

    This calculation returns how many minutes an outage has been active. However, there are instances when outages last for hours, or even days. In these cases, seeing the number of minutes is not as meaningful. You can format how the elapsed time is shown using a function written in Arcade, to show minutes, hours, and days.

    Next, you will add a function for formatting elapsed time.

17. Press Enter two times and copy and paste the following function statement:

    //Define the function name.
    function formatElapsedTime(numMinutes) 
    { 
    //The elapsed time of an outage is not always a whole number.  
        numMinutes = Floor(Abs(numMinutes)); 
    //Using the Floor function, you can round down the time to number of hours and days. 
        var numHours = Floor((numMinutes/60),0); 
        var numDays = Floor((numMinutes/(60*24)),0); 
    //Using a When logic function, you can append the unit prefix to the value. 
        var elapsedTime = When( 
            numHours < 1, numMinutes + 'm', 
            numDays < 1, numHours + 'h ', 
            numDays + 'd ' 
             ); 
          return elapsedTime;  
    }

    Note:

    See the comments (comments start with //) in the expression to review what each portion of the function does.

    

    The function rounds the number of minutes down to get whole numbers, then uses floor division on those rounded minutes to calculate hours and days. Using a When logic function, it then appends the appropriate unit prefix.

    You will now define your final outage duration variable. This line creates a variable named timeFormatted that holds the results of the formatElapsedTime function you just created, applied to the minutesOpened variable to correctly display the elapsed time.

18. Add another line after your function and type var timeFormatted = formatElapsedTime(minutesOpened);

    After calculating the outage duration, you can now calculate the reliability impact index. The reliability impact index is determined by calculating the number of customers impacted by the outage duration.

19. Add another line and type var reliabilityIndex = Floor(($datapoint["ImpactedCustomers"]/minutesOpened),2);

    This new variable takes the Impacted Customers data point and divides it by the minutesOpened variable you created earlier. Since this value will likely be a fraction, applying the Floor function on the entire calculation rounds the number to a value with two decimal points.

    Now that you have the reliability impact index value, you can determine which outages are more severe or likely need more immediate attention. To make it easier to spot these outages on the list, you will create a color variable that will highlight incidents with a reliability impact index greater than 1.

20. Add another line and type var severityColor = IIF(reliabilityIndex > 1, '#C22E00', '#363636')

    The variable uses the IFF function, which returns a given value, in this case, a color, if a condition is true and an alternate one if the value is false. In this case, if the value for the reliability impact index is above the threshold of 1, the color will be red. Otherwise, the color will be gray.

    Once you have your final variables, timeFormatted, reliabilityIndex, and severityColor, you will return them in the expression. This allows you to reference them in the line item template as new attributes to populate the list item.

21. Add a line and type the following at the end of your expression:
    return { 
      attributes: { 
        timeFormatted: timeFormatted, 
        reliabilityIndex: reliabilityIndex, 
        severityColor: severityColor 
    } 
    }

    Your Arcade editor will look like this:

    

    The complete code is:

    var dateOpened = $datapoint.StartDate
    var currentTime =Now()
    var minutesOpened = DateDiff(currentTime, dateOpened, 'minutes');
    
    //Define the function name. 
    function formatElapsedTime(numMinutes)
    {
    //The elapsed time of an outage is not always a whole number. 
        numMinutes = Floor(Abs(numMinutes));
    //Using the Floor function, you can round down the time to number of hours and days.
        var numHours = Floor((numMinutes/60),0);
        var numDays = Floor((numMinutes/(60*24)),0);
    //Using a When logic function, you can append the unit prefix to the value.
        var elapsedTime = When(
            numHours < 1, numMinutes + 'm',
            numDays < 1, numHours + 'h ',
            numDays + 'd '
             );
          return elapsedTime; 
    }
    
    var timeFormatted = formatElapsedTime(minutesOpened);
    var reliabilityIndex = Floor(($datapoint["ImpactedCustomers"]/minutesOpened),2);
    var severityColor = IIF(reliabilityIndex > 1, '#C22E00', '#363636')
    
    return {
      attributes: {
        timeFormatted: timeFormatted,
        reliabilityIndex: reliabilityIndex,
        severityColor: severityColor
    }
    }

22. Click the Done button at the bottom of the window.
23. In the List options pane, scroll down below the Expression text box and in the Line item template, click Source.

    

    Dashboards allows you to use custom HTML to format your list items. Along with advanced formatting, this allows you to create custom visualizations that are not part of the system-defined properties. In the Line item template field, you can use the expression you just created along with HTML to format how each list item will display.

24. Delete the <p>{OBJECTID}</p> line.
25. Copy and paste the following into the editor:
    <div style="background-color:#363636; border-left:3px solid white; padding:0.4rem 0.3rem 0.3rem 0.6rem"> 
    
    <p><span style="font-size:16px; opacity:1">Time elapsed: {expression/timeFormatted}</span></p> 
    
    <p><span style="font-size:14px; opacity:1; padding:1px">{UtilityCompany} - {County}</span></p> 
    
    <p><span style="background-color:{expression/severityColor}; border-radius:5px; font-size:14px; opacity:1; padding:1px 6px">SAIDI: {expression/reliabilityIndex}</span></p> 
    
    </div>

    

    The first tag, <div style>, determines the structure line item. Within the div style, you determine the background color, border, and padding of the line item.

    The next lines that use the paragraph tag, <p>, determine the formatting of each piece of information included in the line item. For your list, you want to display the newly calculated time elapsed, the utility company, and the reliability impact index.

    For each <p> tag, you determine its styling using the <span style> tag and any styling properties. Within the <p> tag, you determine the text that is displayed in the line item. For example, in the first <p> tag, you are using displaying the text “Time elapsed:” and following it with the time elapsed expression.

26. Click Source to preview your list formatting.
27. Click Done.

    Each list item now displays the time elapsed, the associated utility company, and the Reliability Impact Index (SAIDI) value. When the value is higher than the threshold, the value is highlighted in red.

    

Configure the outage indicator

Now that you have a list that itemizes reported outages, the next step is to add an indicator. The indicator gives an at-a-glance summary of the number of outages that are active in the state. In addition to seeing the number of active outages, with the use of a reference value, advanced formatting, and custom HTML, you will create an alert for when an outage has been reported.

1. On the dashboard toolbar, click Add element. Point to the map element, click the right add button, and click Indicator.
2. On the Indicator Select a layer window, click Power Outages (View) - Power Outage Incidents.

   The Indicator window appears.

3. On the Data tab, expand the Reference section.
4. For Reference type, choose Statistic.

   The reference value will be used to determine when a new outage is reported. You will filter the value to only include the outages that are within the last 5 minutes. This will set your baseline for a new outage to be 5 minutes.

5. Next to Filter, click the Filter button.
6. Under Filter, build the following expression:
   • For Field for the condition, click Start Date/Time.
   • For the operator, choose is within the last.
   • For the value, enter 5 and for the unit, choose minutes.

   

   Now that you have the reference value, you will use advanced formatting to set up the data alert that will be added to the indicator title.

7. Click the Indicator tab.
8. For Advanced formatting, click Enable.

   Using Arcade, you will create the variable that will be used to determine when the new outage alert displays using an IFF logic function. Your condition will be based on the reference value you configured. The condition will state that if the count of outages reported within the last 5 minutes is greater than none, the message will be visible. If not, it will be hidden.

9. In the editor, after the first several lines defining variables, add a line and type var visibility = IIF($reference.count_ObjectID > 0, 'visible', 'hidden').

   

   Next, you will return the visibility condition and the rest of what the indicator displays. You will also create the message you want displayed when there is a new outage. In this case, you will configure the message to read “New outage reported in the last 5 minutes”.

10. In the editor, delete the block of code from return { to the last line.
11. Copy and paste the following in its place:
    return { 
        middleText: $datapoint["count_ObjectID"], 
        middleTextMaxSize: 'large', 
        bottomText:'Active outages', 
        bottomTextMaxSize: 'medium', 
        attributes: { 
           visibility: visibility,  
           message: 'New outage reported in the last 5 mins' 
       } 
    
    }

    The return statement is where the different properties of the indicator are defined. For this indicator, you are only using the middle and bottom text areas. You also define the visibility variable that was created along with the message that is displayed when the visibility is true.

    Tip:

    You can define all parts of an indicator using advanced formatting. These properties are ones that would otherwise be defined using the standard configuration settings of the indicator. For a full list of indicator properties that can be defined, see Advanced formatting in an indicator.

12. Click the General tab.
13. In the General options pane, for Title section, click Edit.

    

14. In the rich text editor, click Source.
15. Copy and paste the following into the editor:
    <div style="background-color:#de290033; border-left:2px solid #de2900; box-shadow:0 4px 6px 0 hsla(0,0%,0%,0.2); color:##de2900; margin-bottom:0.4rem; margin-left:0.4rem; margin-right:0.4rem; margin-top:0.1rem; padding:0.7rem; visibility: {expression/visibility}; width:98%"> 
    <span style="font-size:16px">{expression/message} </span> 
    
    </div>

    In this case, HTML is used to define the style properties of the message. The first tag, <div style>, determines the structure. Within the <div style> tag, several properties, such as background color and border, are set. The visibility of the message is controlled by the visibility expression you created earlier.

16. Click Source to preview your message.
17. Click Done.

    Your outage indicator now shows the total number of active outages in the state.

    

    When an outage has been reported in the last 5 minutes, the alert message appears at the top.

    

Configure the customer impact indicator

The last element you will add is an indicator summarizing the number of customers impacted by the outages, broken down by whether the outage type was planned or unplanned. Knowing the number of impacted customers is important to better assess the situation.

1. In the dashboard toolbar, click Add element. Point to the indicator element, and click the add button at the top. Choose Indicator.
2. In the Indicator Select a layer window, click Power Outages (View) - Power Outage Incidents.
3. In the Data options pane, for Statistic, choose Sum. For Field, choose Impacted Customers.

   

4. Expand the Reference section and for Reference type, choose Statistic.

   More options appear in the Reference section.

5. For Filter, click the Filter button.
6. From the Field for the condition drop-down list, choose Outage Type.
7. For the operator, confirm equal is selected. In the Value tab, choose Planned.

   

8. For Statistic, choose Sum. For Field, choose Impacted Customers.

   

   You now have the value and reference values to use in your indicator's display. In this case, the value is the total number of impacted customers, and the reference value is the number of impacted customers from planned outages.

9. Click the Indicator tab.

   Values, reference values, and predefined calculations can be directly injected into the indicator's visualization using curly brackets {} or by using the Fields: {} button.

10. In the Indicator options pane, enter the following:
    • For Top text, type Impacted customers.
    • For Middle text, type Total:{calcualted/value}.
    • For Bottom text, type Planned:{calculated/reference} Unplanned: {calculated/difference}.

    

11. Expand the Value formatting section.
12. Turn off the Unit prefix.

    

    This allows you to see the exact values for the impacted customers.

13. Click Done.

    The indicator display is now populated with the total number of impacted customers, along with how many are impacted by planned and unplanned outages.

    

    Next, you will arrange the dashboard indicators.

14. Point to the left edge of the indicator column to get a resize cursor and drag the column to make the map larger and the indicators smaller.

    

15. In the map element, zoom and pan the map to center the data around the state of California.
16. If necessary, close the Layout panel to better preview your dashboards.

    

17. On the dashboard toolbar, click Save and choose Save to save your dashboard.

    

In this tutorial, you created a power outage map and a dashboard that allows you to quickly view incoming outages in the state of California. Using advanced formatting of list and indicator elements, you were able to derive and visualize data that was not readily available. In addition to visualizing new information, you were able to configure an alert for when an outage occurs. Being able to see outages as they come in can help cities, counties, and states make informed decisions and mobilize resources to solve problems more efficiently.

You can find more tutorials in the tutorial gallery.

Acknowledgements

• California Governor's Office of Emergency Services (Cal OES) Tracked Power Outage information for California.
• Streets (Night): Esri, TomTom, Garmin, FAO, NOAA, USGS, © OpenStreetMap contributors, and the GIS User Community.