Table of Contents

Overview

The Dashboard Interpreter feature enables granular control and customization of the Dashboard that a user sees in the Eleos application on a user-by-user basis, without requiring you to define individual elements in the Eleos Platform interface or create different dashboard definitions for different users.  This is accomplished through a combination of database scripting that provides parameterized instructions to the interpreter for a given user, and simple, lightweight definition of certain elements in the platform.


There are three ways in which a dashboard can be customized per-user by the interpreter at time of writing:

  1. 1. Specifying a dashboard logo 
  1. 2. Dynamically building and formatting a customized Payroll card 
  1. 3. Dynamically building and formatting one or more customized Info cards


Feature Usage

The Dashboard Interpreter can be easily enabled or disabled by the appsettings.json Boolean value "DashboardInterpreterEnabled", in the "Settings" section of the file: 
 


When enabled, Eleos Core will begin downloading Dashboard definitions for Dashboard codes that it encounters on users that are logging in or verifying authentication tokens and building them in code instead of linking the Dashboard Code to the Platform.  No other actions are required, though without further customization, the resulting Dashboard will be identical to its corresponding definition in the Eleos Platform interface.


A majority of the customization that is possible with this feature takes place in the user SQL procedure 'ELEOS.usp_ValidateUser_Custom_Template', if SQL contracts are implemented, the procedure contains its own documentation on usage intended to be a quick reference when customizing dashboards, but this document will cover each customization option in greater detail.  If ELEOS.usp_ValidateUser_Custom_Template does not exist in the database and SQL contracts are not implemented, then customization will have to be made in the user-defined SQL function ELEOS.udf_UserDashboardProperties.


SQL Scripting Overview

If SQL Contracts are Implemented

If SQL contracts are implemented, ELEOS.usp_ValidateUser_Custom_Template is a custom template procedure that is executed during user login and token validation.  It makes use of a temp table called #ASR_DashboardProperties to define properties that are used to build and customize a dashboard.  Those properties use predefined column name prefixes with delimiters to specify what type of customization is being made and grouping them by matching suffixes.  


The #ASR_DashboardProperties table is intended to be a dictionary representation of all the key-value pairs that should be returned from the invoking procedure as a table.  When returned, the table represents a collection of key-value pairs where the name of the column is the Key, and the value for that column is the value. All customization properties must be specified in the #ASR_DashboardProperties table as column names (formatted appropriately according to the feature they are customizing).


If SQL Contracts are Not Implemented

If SQL contracts are not implemented and ELEOS.usp_ValidateUser_Custom_Template does not exist, then ELEOS.udf_UserDashboardProperties is executed during user login and token validation.  It makes use of a locally scoped table variable titled @Fields to define properties that are used to build and customize a dashboard.  Those properties use predefined column name prefixes with delimiters to specify what type of customization is being made and grouping them by matching suffixes.   Changes can be made to the @Fields table to make customizations.


Eleos allows a user's dashboard to specify a different logo than the default that is normally displayed.  This can help users distinguish between different Divisions within the application, for example, or can serve to simply provide a more customized user experience


If SQL Contracts are Implemented

To specify a different logo, the #ASR_DashboardProperties table must contain a column labeled 'LogoRef'.  The value for that column will be set as the user's dashboard logo reference.

;INSERT INTO #ASR_DashboardProperties (
         [Id]
        ,[Name]
        ,[Value]    )
SELECT           [Id]        = 'ASRDRV' -- DriverName
        ,[Name]     = 'LogoRef'
        ,[Value]     = 'my_eleos_logo_ref'

The above would set 'my_eleos_logo_ref' as the dashboard's logo reference. 


NOTE:  The value for 'LogoRef' is determined by Eleos.  Custom logos must be provided to Eleos first, after which they will provide the corresponding logo_ref value that should be used to display that logo. 


If SQL Contracts are NOT Implemented

If SQL contracts are not implemented, insert records into the @Fields table manually. Records no longer need the user id, and only require a defined column with the column name and the value itself.

DECLARE @Fields TABLE (
    [LogoRef]    VARCHAR(50)
)
INSERT INTO @Fields VALUES ( 'my_eleos_logo_ref' )


Building and Formatting a Custom Payroll Card

Eleos Dashboards support a 'Payroll' type card that displays basic label-value pairs of information to a user and allows the user to tap on the card to navigate to the Payroll screen for more details.  At time of writing, there is no way to define a true Payroll card solely from the Eleos App Manager.  The Dashboard Interpreter circumvents this limitation by allowing users to very easily define a basic Payroll card with little to no additional configuration.


There are three requirements to enable the custom Payroll card: 

  1. 1. Defining an Info Card on the dashboard with a "Payroll" header 
  1. 2. Ensuring the appsettings.json value "PayrollCardHeader" matches the header chosen above 
  1. 3. Returning at least one [PaySummary_{Label}] field within #ASR_DashboardProperties (see "Pay Summary Fields" below for more info)

The default Info Card header that the interpreter expects is "Payroll", but this can be changed to whatever is desired so long as that header is the value of "PayrollCardHeader" in appsettings.json. 

In addition, there are several optional fields that may be specified to further customize the payroll card: 

Note that these do not require delimiters or matching suffixes, as they configure the overall card itself.  


Define a "Payroll" Info Card

The Dashboard that a user will see must have an Info Card with a "Payroll" header.  This card can be placed anywhere among other items on the Dashboard.  The interpreter will transform this card into a Payroll card, displaying key-value pairs sourced from #ASR_DashboardProperties.




Set "PayrollCardHeader" in appsettings.json

The appsettings value "Settings.PayrollCardHeader" must have a string value that matches the Header defined on the info card above. 


Pay Summary Fields

A Pay Summary field is simply a key-value pair of information that will be displayed to the user on the Payroll card.  Any number of Pay Summaries can be defined in ELEOS.usp_ValidateUser_Custom_Template, but at least one must be specified if a Payroll card is desired.


Pay Summary fields all share the common column name prefix 'PaySummary' and use a pre-defined delimiter (currently '_') to distinguish the Label for that Summary item.  Pay Summary fields are tied together by their label, so it is important to ensure that fields describing the same summary item have the same label.  These fields will be the column name in the #ASR_DashboardProperties table, so additional table columns will need to be added to #ASR_DashboardProperties for each additional summary item.  For example, inserting the following into the #ASR_DashboardProperties table would create a line item labeled 'Example' with value of 'Example Text', and another line item labeled 'Date' with the current date formatted into a Date value type:

;INSERT INTO #ASR_DashboardProperties (
	 [Id]
	,[Name]
	,[Value]	)
VALUES 
	( 'ASRDRV', 'PaySummary_Example', 'Example Value' ),
	( 'ASRDRV', 'PaySummary_Date', CAST(SYSDATETIMEOFFSET() AS VARCHAR(100)) ),
	( 'ASRDRV', 'PaySummaryValueType_Date', 'date'  )


The two fields that end in '_Date' are for the same line item; PaySummary_Date defines the overall {Key} ('Date') and value for the line item, and PaySummaryValueType_Date specifies that the value type for the "Date" line item should be 'date', which will prompt Eleos to format it into an easy-to-read date. 


Note: If SQL Contracts are not yet implemented, instead of inserting into #ASR_DashboardProperties, you will need to add additional table columns to @Fields for each additional summary item.  Do this by declaring the @Fields table columns and insert values for each.


Required Pay Summary Fields

A white box with black text Description automatically generated

Optional Pay Summary Fields

A screenshot of a computer Description automatically generated


Building and Formatting Custom Info Cards

Info Cards are generic text cards that display on a user's dashboard.  They can optionally include an image and one or more actions that can be specified in multiple ways in ELEOS.usp_ValidateUser_Custom_Template.


While the Payroll Card feature only supports a single Payroll card that must have a "stub" pre-defined in the dashboard's definition, Info Cards do not have this limitation.  The Dashboard Interpreter can update an already-defined Info Card with a matching header, or it can build an entirely new undefined Info Card and add that to the dashboard in the desired position.


Info card fields all share the common column name prefix 'Info{Property}',  where {Property} is the name of the info card property that field should control (such as 'InfoHeader' or 'InfoText').  Like Payroll card fields, each Info Card field must contain a delimiter (currently '_') to distinguish the header for that Info Card (e.g. [InfoHeader_My Header Text]).  Also like Payroll Card fields, Info Card fields are grouped together by their {Header}, so it is important to ensure that fields describing the same Info Card all have the same Header text after the field delimiter.


This means that a given 'InfoHeader_{Header}' field is the "parent" field for an info card, and its {Header} value will be used to identify the remaining fields for that card.  For example, the following query to insert into the  #ASR_DashboardProperties table would add a new Info Card to the dashboard (or modify an existing with the same Header):

;INSERT INTO #ASR_DashboardProperties (
	 [Id]
	,[Name]
	,[Value]	)
VALUES 
	( 'ASRDRV', 'InfoHeader_Example Card', 'My example cards header text' ),
	( 'ASRDRV', 'InfoText_Example Card', 'This is text that would display on the card' ),
	( 'ASRDRV', 'InfoActionCode_Example Card', 'ACTION-CODE'  )


This would create (or modify) an Info Card on the dashboard with the Header 'Example Card', giving it the actual header and text values selected into the table and embedding the action defined by 'ACTION-CODE' into the card, making it tappable. 


Note: If SQL Contracts are not yet implemented, instead of inserting into #ASR_DashboardProperties, you will need to add additional table columns to @Fields for each info card. Do this by declaring the @Fields table columns and insert values for each.


Required Info Card Fields
A white rectangular box with black text Description automatically generated


Optional Info Card Fields
A screenshot of a computer Description automatically generatedNotes on Actions

If you would like the card to have more than one Action, either via action code or JSON definition, the field for the additional action must have the same column name prefix and header label but can be followed by any other text.  Consider the following abridged example: 


;INSERT INTO #ASR_DashboardProperties (
	 [Id]
	,[Name]
	,[Value]	)
VALUES 
	( 'ASRDRV', 'InfoAction_Example', 'FIRST-ACTION-CODE' ),
	( 'ASRDRV', 'InfoAction_Example_2', 'SECOND-ACTION-CODE' )


This will include both 'FIRST-ACTION-CODE' and 'SECOND-ACTION-CODE'  as actions on the 'Example' Info Card. 


As a result, implementers must be careful to ensure that different Info cards have distinct {Header} values, even if their actual Header text values will be similar to one another (or even identical).  For example: 


VALUES 
	( 'ASRDRV', 'InfoHeader_Example', 'Some header' ),
	( 'ASRDRV', 'InfoHeader_Example2', 'Some other header' ),
	( 'ASRDRV', 'InfoActionCode_Example', 'ACTION-CODE' ),
	( 'ASRDRV', 'InfoActionCode_Example2', 'OTHER-ACTION-CODE' )
The Dashboard Interpreter will correctly identify 'Example' and 'Example2' as different Info Cards, but the extensible nature of Action definitions would result in both action codes being linked to the `Example` card, since both action code fields begin with 'InfoActionCode_Example'.  'Example2' would only have 'OTHER-ACTION-CODE' linked, because it is the only field that begins with 'InfoActionCode_Example2'. 

To avoid this, simply change the {Header} identifier to something more distinct, e.g.: 

VALUES 
	( 'ASRDRV', 'InfoHeader_First', 'Some header' ),
	( 'ASRDRV', 'InfoHeader_Second', 'Some other header' ),
	( 'ASRDRV', 'InfoActionCode_First', 'ACTION-CODE' ),
	( 'ASRDRV', 'InfoActionCode_Second', 'OTHER-ACTION-CODE' )
This will result in the same two Info Cards with the same headers as above, but only one action linked to either of them. 


Note: If SQL Contracts are not yet implemented, instead of inserting into #ASR_DashboardProperties, you will need to add each additional action to the @Fields table.  When making changes to the @Fields table to set the Header values the syntax is slightly different than the examples shown above.