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-defined SQL function 'ELEOS.udf_UserDashboardProperties'.  The function 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. 


SQL Function Overview

ELEOS.udf_UserDashboardProperties is a user-defined function that 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.   


The @Fields table is intended to be a "flat" representation of all of the key-value pairs that should be returned from the function as a single row in the table.  Once row values are set, the bottom of the function pivots the table into 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 @Fields table as column names (formatted appropriately according to the feature they are customizing). 


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. 


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

DECLARE @Fields TABLE ( 
    [LogoRef]    VARCHAR(50) 
) 
 
INSERT INTO @Fields VALUES ( '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. 


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 from udf_UserDashboardProperties (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 udf_UserDashboardProperties. 




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 udf_UserDashboardProperties, 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 @Fields table, so additional table columns will need to be added to @Fields for each additional summary item.  For example, selecting the following into the @Fields 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: 

DECLARE @Fields TABLE ( 
     [PaySummary_Example] VARCHAR(100) 
    ,[PaySummary_Date] VARCHAR(100) 
    ,[PaySummaryValueType_Date] VARCHAR(100) 
) 
 
INSERT INTO @Fields VALUES ( 
     [PaySummary_Example] = 'Example Value' 
    ,[PaySummary_Date] = CAST(SYSDATETIMEOFFSET() AS VARCHAR(100)) 
    ,[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. 


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


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 a 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').  Similar to 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 similar to 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 select into the @Fields table would add a new Info Card to the dashboard (or modify an existing with the same Header): 

DECLARE @Fields TABLE ( 
     [InfoHeader_Example Card] VARCHAR(100) 
    ,[InfoText_Example Card] VARCHAR(100) 
    ,[InfoActionCode_Example Card] VARCHAR(100) 
) 
 
INSERT INTO @Fields VALUES ( 
     [InfoHeader_Example Card] = 'My example cards header text' 
    ,[InfoText_Example Card] = 'This is text that would display on the card' 
    ,[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. 



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 @Fields 
SELECT  [InfoAction_Example] = 'FIRST-ACTION-CODE' 
       ,[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: 

[InfoHeader_Example] = 'Some header' 
,[InfoHeader_Example2] = 'Some other header' 
,[InfoActionCode_Example] = 'ACTION-CODE' 
,[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.: 

[InfoHeader_First] = 'Some header' 
,[InfoHeader_Second] = 'Some other header' 
,[InfoActionCode_First] = 'ACTION-CODE' 
,[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.