Dashboards for Employee Portal

There are several phases of configuring Dashboards:

1. Create a Dashboard that will be assigned to users. Multiple dashboards may be created (for example, Sales dashboard and Support dashboard).

2. Create a Widget to assign query data, allowing it to display on a dashboard.

3. Configure Push Notifications for widgets to be automatically updated when data changes in SAP Business One. Otherwise, the dashboard must be manually refreshed.

4. Enable Dashboard Access for a web User by assigning the Dashboard or Dashboard Admin role to the user.

5. Log in as a user to Configure Dashboard Layout. Orient widgets on a dashboard to configure its web layout.

Create a Dashboard

Dashboards display widgets together to give a sense of data for a specific business area. For example, one dashboard could be for Sales Reps to show them their ongoing sales versus targets, while another dashboard could be for a Service team to display metrics related to open Service Calls.

Multiple dashboards may be created on the same system, and user roles can be applied to only display the dashboard for its intended audience.

To create a dashboard:

1. In SAP Business One, go to InterConnect Manager AddOn > Manage Dashboards.

2. Add a dashboard using the + button on the upper-right, or edit an existing dashboard by using the existing dashboard’s golden arrow.

3. Create a unique dashboard name so that an admin can recognize what it’s for.

4. If desired, allow date filtering in the dashboard to filter data based on the defined date range.

5. Assign roles to the dashboard. This will allow all selected roles to view the dashboard and its widgets.

6. If desired, apply optional filter settings. This will allow the user to further refine their view of the widget data.

7. Add widgets. See the section Create a Widget below for more details.

8. Save the dashboard when it’s ready, press the Add or Update button to apply changes.

9. Configure the layout on the web. See Configuring Dashboard Layout for instructions.

Create a Widget

Dashboard widgets allow for configurable query-based views of your data. Widgets can be easily configured out-of-the-box with distinct layouts that are specific to your data reporting needs.

Widgets can be added to existing dashboards. If you have not already created a dashboard, this must be done first, see Create a Dashboard above.

To create or edit a widget:

1. In SAP Business One, go to: InterConnect Manager AddOn > Manage Dashboards.

2. Select the dashboard using the golden arrow.

3. Add a new widget using the + button, as shown in the screenshot below, or use an existing widget’s golden arrow to edit that widget.

   

4. Fill in the widget details as described below:

   

   Widget fields
   Field	Description
   Widget Name (1)	Used by an admin to identify the widget.
   Display Label (2)	Label displayed to the end user who will see the dashboard.
   Widget Type (3)	The widget type controls what type of widget this will be displayed as. Each widget type has its own query and parameter requirements. Once a widget type is selected, further details (outlined below) will be needed.
   Query Category (4)	This must be a B1WebAPI query category. For example B1WebAPI_OP relates to Opportunity Manager for Employee Portal while B1WebAPI_OEC could be a custom category created for the company "OEC Computers".
   Query Name (5)	This identifies which query is assigned to this widget.
   Number of Columns (9)	This defines how many columns the widget will take up. Smaller widgets may be configured to span several columns, however larger widgets have set defaults that can't be changed. All out-of-the-box widget types are designed to fit within the 4-column layout of the dashboard.
   Widget Parameters (8)	This depends on which widget type is selected.
   Enable Real-Time Updates (6)	May be selected if data types have been configured. See Push Notifications below if you wish to enable this feature.
   Refresh on Change of (7)	This depends on which widget type is selected. When Enable Real-time Updates is enabled, changes for the select document actions will be auto-refreshed on the dashboard.

5. Press the Add/Update button to save the widget to the dashboard.

Widget Query Formats

Bar Widgets

Bar Widgets display a single series of data in a vertical bar chart. This type of widget is good for comparison data, for example, year-over-year values, or data that’s useful to see side-by-side.

Bar Widget Query Format

This query format is used by Bar, Donut, and PieChart widgets.

Queries of this type should have at least 2 columns. The first column is assumed to be the label column and the second is the value column. Additional fields beyond the first two are ignored. Each row in the query will display a segment of data (such as a bar or pie-piece).

See your installed version of the query B1WebAPI_Dashboard/SalesByRep for a sample with data. In SAP Business One, go to: Tools > Queries > User Queries > B1WebAPI_Dashboard > SalesByRep.

Bar Widget Query Parameters

None

Donut Widgets

Refer to PieChart Widgets below.

Gauge Widgets

A Gauge widget displays a value relative to a target. Gauge widgets are good for displaying data related to a known target (for example sales progress month-to-date versus monthly targets), or metrics that have a known “good” versus “bad” value (for example, open service calls per analyst).

Gauge Widget Query Format

The Gauge widget only uses the first row of the query results. It pulls the target value from a column named ‘Target’ and the value to display from a column named ‘Actual’.

See your installed version of the query B1WebAPI_Dashboard/SalesRevGrowthYTD for a sample with data. In SAP Business One, go to: Tools > Queries > User Queries > B1WebAPI_Dashboard > SalesRevGrowthYTD.

Gauge Widget Parameters

• Decimal Places: Defines how many decimal places will be displayed on the gauge. The query may include more precision.
• Display Yellow: [Y|N] Yes (Y) will show a third region in yellow on the gauge. No (N) will display only red and green regions.
• Yellow Threshold: This value must be between 1-100. It defines the percent of the target value that should display yellow. For example, if the target is 10 and the Yellow Threshold is 80, yellow will be displayed between 8 and 10.
• Larger Better: [Y|N] Yes (Y) will show green for larger numbers, while No (N) will show green for smaller numbers.
• Max: Upper bound of the gauge.
• Min: Lower bound of the gauge.

GeoChart Widgets

The Geo Chart displays regional data on a shaded country map by province or state. The country codes are based on the ISO 3166-1 alpha-2 standard en.wikipedia.org/wiki/ISO_3166-1_alpha-2.

Geo Chart Widgets are useful for data that is regional (such as national sales data), or where location is important (for example, Location-based service call coverage).

GeoChart Widget Query Format

For the query a minimum of two columns are expected. The first must be the country and province code for the region in the format [ISO 3166-1 country code]-[ISO 3166-2 subregion code] e.g. US-CA for California. The second column must be numeric and will decide the shading. Any additional columns will be included in the hover text.

See your installed version of the query B1WebAPI_Dashboard/SalesMapUSA for a sample with data. In SAP Business One, go to: Tools > Queries > User Queries > B1WebAPI_Dashboard > SalesMapUSA.

GeoChart Widget Parameters

• Region: Defines which region will be displayed by the geo-map.

Grid Widgets

Displays a grid based on the results of the query. Optionally displays a link column. The URL Template param is used to build the HREF for a link column by substituting the Link Column value in the string format string (see for blog.stevex.net/string-formatting-in-csharp/ for details).

Grid Widget Query Format

Each column in the query is displayed in order with the column name matching the alias for the column. If the link column attributes are set these columns will be extracted to create a link column in their place.

Because space is limited in a dashboard, restrict the query to 3-6 columns.

Grid Widget Parameters

• Link Column Name: Defines which column is used in the link URL.
• Display Column Name: Defines which query column is used for the link text.
• URL Template: Defines the template for the URL. {0} is used as a placeholder that will be replaced by the Link Column Name.
• Link Column Title: Defines the label that a user will see for the link column.

KPI Widgets

This widget displays Key Performance Indicator results, highlighting how closely the actual value compares to the target value. A previous value can also be displayed for comparison to the current period.

Good examples of usage for KPI Widgets include data that’s about targets versus actuals. For example, sales-to-date versus target sales (say, a value that is more than 15% below a sales target would be yellow, more than 25% below target would be red), or hours to close a service call versus commitments (say, 10% below commitment target is yellow, but above commitment target is red)

KPI Widget Query Format

The KPI widget only uses the first row of the query results. It pulls the target value from a column named ‘Target’ and the value to display from a column named ‘Actual’. Optionally, if there is a column called ‘Previous’ that will be displayed as well.

A supplementary table ZEDS_KPI_TARGETS (Portal Dashboard KPI Targets) can be used to set target details, which can then be queried, such as is found in the Dashboard Widget “My Sales > Sales Revenue MTD by Rep” (using query: B1WebAPI_Dashboard/SalesRevCurrentMonthKPI_ByRep).

KPI Widget Parameters

• Decimal Places: Defines how many decimal places will be displayed on the KPI. The query may include more precision.
• Format: [Currency|Percent|Number]
• Display Yellow: [Y|N] Yes (Y) will show a third view in yellow on the KPI. No (N) will display only red and green views.
• Number Suffix: (Optional)
• Larger Number Better: [Y|N] Yes (Y) will show green for larger numbers, while No (N) will show green for smaller numbers.

LineChart Widgets

Line Chart Widgets display one or more series of data as lines on a chart. These are ideal for displaying trends over time.

LineChart Widget Query Format

Column 1 should be called ‘Category’ and contains the name of the series.

Column 2 should be called ‘Label’ and contains the name of the period.

Column 3 should be called ‘Total’ and contains the value to be charted. Each row represents a data point with all series displayed together in a single query.

LineChart Widget Parameters

• Height in pixels: This numeric value determines how tall the graph is in the browser.
• Min Value (blank for auto): Starting value for the line chart. Leave blank for a automatic calculation of the minimum value based on the report data.
• Max Value (blank for auto): Upper value for the line chart. Leave blank for a automatic calculation of the maximum value based on the report data.

PieChart Widgets

Pie chart widgets are good for displaying data out of a hundred percent (for the analogy of “pieces of the whole pie”).

An alternative view of a “pie” chart is the “donut” chart. The Donut widget provides a slightly different visualization for the same type of data used in Pie charts.

This uses the Bar Widget Query Format details listed above.

Widgets At-A-Glance

Widget Type	Widget Description	Query Requirements
Bar	Displays a single series of data in a vertical bar chart.	Assumes a query with at least 2 columns. The first one is assumed to be the label column and the second is the value column. There is one bar for each row in the query.
Donut	Displays a single series of data in a donut chart (similar to pie chart).	Assumes a query with at least 2 columns. The first one is assumed to be the label column and the second is the value column. There is one section of donut each row in the query.
FunnelChart	Displays a funnel chart using d3 funnel. Funnel charts have two variables Stage and Total.	Column 1 should be aliased [Stage], Column 2 should be called [Total].
Gauge	A gauge widget displays the status of data compared to expected high and low values.	The Gauge widget only uses the first row of the query results. It pulls the target value from a column named ‘Target’ and the value to display from a column named ‘Actual’.
GeoChart	The Geo Chart displays regional data on a shaded country map by province or state. The country codes are based on the ISO 3166-1 alpha-2 standard (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)	For the query a minimum of two columns are expected. The first must be the country and province code for the region in the format {ISO 3166-1 country code}-{ISO 3166-2 subregion code} e.g. US-CA for California. The second column must be numeric and will decide the shading. Any additional columns will be included in the hover text.
Grid	Displays a grid based on the results of the query. Optionally displays a link column. The URL Template param is used to build the HREF for a link column by substituting the Link Column value in the string format string (see for http://blog.stevex.net/string-formatting-in-csharp/ for detail).	Each column in the query is displayed in order with the column name matching the alias for the column. If the link column attributes are set these columns will be extracted to create a link column in their place.
KPI	This widget displays Key Performance Indicator results, highlighting how closely the actual value compares to the target value. A previous value can also be displayed for comparison to the current period.	The KPI widget only uses the first row of the query results. It pulls the target value from a column named ‘Target’ and the value to display from a column named ‘Actual’. Optionally, if there is a column called ‘Previous’ that will be displayed as well.
LineChart	Displays one or more series of data as lines on a chart. Ideal for displaying trends over time.	Column 1 should be called ‘Category’ and contains the name of the series. Column 2 should be called ‘Label’ and contains the name of the period. Column 3 should be called ‘Total’ and contains the value to be charted. Each row represents a data point with all series displayed together in a single query.
PieChart	Displays a pie chart based on the results of the query.	Assumes a query with at least 2 columns. The first one is assumed to be the label column and the second is the value column. There is one pie slice for each row in the query.

Dashboards At-A-Glance

Out-of-the-box, three dashboards are provided:

Widget Query Reference

Available out-of-the-box queries and a brief description are provided below.

Configure Push Notifications

Push notifications allow Dashboard widgets to be auto-refreshed whenever data is updated in B1. This is an optional feature that may be enabled. If push notifications are not enabled, simply refreshing the page, or navigating away and coming back to the dashboard has the same affect.

Setup involves several steps:

1. Enabling Push Notifications in general
2. Configuring each specific object for use with Push Notifications
3. Enabling Push Notifications in Employee Portal
4. Assigning Push Notifications to a Dashboard Widget

Enabling Push Notifications

To enable push notifications:

1. Enable CLR Support for .net stored procedures as described by Microsoft’s documentation: msdn.microsoft.com/en-us/library/ms131048.aspx.
2. Install a stored procedure using SQLCMD mode (contact your Services implementation consultant for this file). To enable SQLCMD mode, in SQL Management Studio, go to Query - SQLCMD. If installation is successful, you’ll see a new stored procedure called ZEDS_SendPushEvent.
3. Convert B1Push to an application in IIS. To do this:
   • In IIS on the B1 server, expand the B1WebAPI website.
   • Right-click on the folder B1Push and select Convert to application….

   • The Add Application wizard should auto-select the B1WebAPI’s application pool and folder, as shown:

     

   • Press OK to finish converting the folder to an application.

Configuring an object for use with Push Notifications

Once Push Notifications are enabled, each desired object must be configured so it can be used in Push Notifications.

To configure an object for push notification:

• In SAP Business One, open: Tools - User-Defined Windows… - ZEDS_PUSHEVENTS (Portal Push Events)
• In this window, fill in:
  • Code - enter a unique Code (the next unique number is fine).
  • Name - enter the same value used for Code.
  • Object Type - enter the object type number. For supported document types, refer to Supported DI-API object types. For example, “17” refers to Sales Orders.
  • For Product - enter a product code, as defined in ZEDS_APPS, where this object will be used. Typically this is for Employee Portal (ZEP) for Dashboard user, however this may be used with Interconnect (ZWFAPOR).
  • Summary Query - leave blank
  • Tracking options - Place a check-mark in any transaction type that will be needed for this object type. This may be changed later, if desired.
    • Track Updates
    • Track Deletes
    • Track Cancels
    • Track Closing
    • Track Adds

  For example, the screenshot below shows that Push Notifications may be used with oOrders whenever they are updated or added.

  

Enabling Push Notifications in Employee Portal

In versions 93.2 through 93.6, Push Notifications need to be activated within the web.config file for Employee Portal. This can be done by enabling the options outlined below.

1. Add a key for ValidationSettings:UnobtrusiveValidationMode set to None.
2. Add the targetFramework="4.5" property to the httpRuntime setting.

<appSettings>
    <!-- ... -->
    <add key="ValidationSettings:UnobtrusiveValidationMode" value="None" />
    <!-- ... -->
</appSettings>
<system.web>
    <!-- ... -->
    <httpRuntime maxRequestLength="102400" executionTimeout="1200" targetFramework="4.5" />
    <!-- ... -->
</system.web>

Assigning Push Notifications to a Dashboard Widget

Once Push Notifications are enabled, and an object is configured, that object may be used by a widget to auto-refresh its data.

If you have not already done so, you will need to enable Push Notifications, and configure objects to be used with push notifications before you can proceed. See the previous sections above for these instructions.

To assign Push Notifications to a widget:

• Go to: InterConnect Manager AddOn - Manage Dashboards.
• Open your desired dashboard and widget.
• On the Edit Widget screen, place a check-mark in the Enable Real-Time Updates check-box.
• In the “Refresh on change of” pane, place a check-mark for every object and action type desired. If you do not see your desired object and transaction type, ensure you have configured objects for push notifications taking care to fill in the correct “For Product” code (in this case, ZEP)
• Press OK to apply the updates
• In IIS, recycle the Employee Portal application pool.

At this point, push notifications will be enabled for configured widgets.

User Dashboard Access

By default, users do not have access to Dashboards. In order to see the “Dashboards” menu, a user must have the Dashboard or Dashboard Admin role assigned to their user.

To enable user access to dashboards:

• In SAP B1, open the employee’s HR record. To do this, go to: Human Resources > Employee Master Data.
• Edit the user’s details by pressing the user’s InterConnect User Setup button. Note that the user must already be configured, as we are simply adding access to the existing user. If the user is not already configured, set up the user as described in Managing Users for Employee Portal.
• Ensure the Dashboard or Dashboard Admin role is checked. Also ensure any dashboard-specific roles are assigned to the user, as configured on the dashboard admin.
• Update the user to apply changes.
• On the web, log out and log back in to see the Dashboard link.

B1 Access to dashboards

Once an employee user is configured for web access, that user can log into B1 to see their assigned Dashboards within the B1 client (assuming they have an B1 user ID associated with their Employee record).

To view the dashboards within the SAP Business One client:

• Configure the web user as described above.
• Log into SAP Business One with the configured B1 user.
• Start InterConnect Manager Add-On.
• Open InterConnect Manager AddOn > Portal Dashboard (marker 1 below) and wait a few seconds while the B1 client logs into the Portal Dashboard.

  

  If the B1 user can’t see this menu option, ensure the Portal has the appropriate Portal roles and B1 user ID assigned.

• Select and view Portal Dashboards (marker 2 below).

  

Configure Dashboard Web Layout

Once a Dashboard has been created and Widgets have been assigned to the dashboard, it can be displayed on the web. Dashboard layouts can be managed on the web by users with the role Dashboard Admin.

1. Log into Employee Portal as a user with Dashboard Admin role.

2. On the Dashboard page, select the dashboard that will be edited using the drop-down on the upper left (see marker 1 on the screenshot below).

   

3. Press the settings button (see marker 2 in the screenshot above) to open the dashboard settings.

4. Drag widgets from the side panel to add them to the dashboard. Drag them from the dashboard to the side panel to remove them from the dashboard.

   

   

   

5. Resize widgets to make them take up more or less space on the dashboard. This can be used to make complicated charts larger, or to condense up to 4 widgets into the same row. Not all widgets can be resized.

   

   

6. Move widgets into position if they have been pushed to new rows due to automatic resizing.

   

7. Delete empty rows when they are no longer needed for new widgets.

   

8. When edits are done, press the Save Layout button to apply changes.

   

9. Review the dashboard layout to confirm new widgets are displaying the desired info.

   

At this point, the dashboard is configured and ready for general use.