ASR Solutions

Overview

In Eleos version 1.57, the platform introduced the User Refresh API, enabling immediate updates to a driver’s app experience based on client-defined criteria and triggers, without requiring the driver to manually interact with the app to view UI changes. This is beneficial for significant UI changes that a client would want their drivers to see update in real-time. I.E. refreshing and updating a dashboard to show changes for a specific driver in response to an action they perform. 

The User Refresh Feature is only available for use after receiving the Q1 2025 release of ASR's Eleos Integration. 

Enabling, Disabling, And Configuring The User Refresh Feature

User Refresh can be enabled or disabled within the appsettings.json file where the integration is deployed. A client can configure the interval at which the refreshes occur when they are triggered. This interval is in seconds, and the lower this value the more frequently the integration refreshes. The higher this value, the less frequently these will process.

Note: Because refreshes happen via the Eleos API, refreshing is limited to a maximum of 300 requests or drivers per 5 minutes. If refreshing for a large group of drivers greater than 300, processing for each driver will occur until that limit is reached, and then after the 5-minute mark has passed, additional drivers (in increments of 300 per 5 minutes) will be processed at a time.

Within the appsettings.json file under the general “Settings” section, a client can find the “UserRefreshEnabled” setting to enable and disable the refresh, and the “UserRefreshIntervalSeconds” setting to adjust the frequency that refreshes are processed:

Note when adjusting these settings, the UserRefreshEnabled setting must be either true or false, and the UserRefreshIntervalSeconds setting must be an integer value greater than zero. 

How User Refresh Processing Works

All triggered user refreshes are first inserted as records into a queue table. This queue table is the ELEOS.UserRefreshRequests table that is in your database connected to the integration. When a user refresh is triggered either from the database or an HTTPS request, it will be inserted into this table. The integration then has a background service that when enabled and configured (via the settings in the section above) will run on a set interval and each time process refreshes that are represented as records in the queue table. This processing from the background service is what then reaches out to the Eleos API for making the refreshes happen. After this processing occurs every interval, the records in the queue are then removed.

It should be noted that if refreshes for invalid users (such as users that do not exist) are triggered, processing will continue and refresh any valid users. Invalid users will get removed from the table once the background service finishes processing, so that failed refreshes are not reported back and do not halt additional processing.

Triggering A User Refresh From The Database

Prior to the User Refresh API being available, if a driver was not seeing updates persist to their app it was recommended that they navigate to another screen within their application (such as their Load List or Messages), and swipe down from the top of the display to force a refresh from Eleos. While this is still possible to “manually” refresh the application, this can now be triggered from the database to refresh the application more seamlessly for drivers:

Within your database that is connected to the integration, executing the ELEOS.usp_AddUserRefreshRequest procedure and passing in a driver’s name, team, terminal, or even indicating all drivers allows you to trigger a refresh for a user, subsets of users, or all users. Examples of these SQL statements are listed below. The ELEOS.UserRefreshRequests table will also contain all refreshes that are currently in processing, and selecting from this table will show users that refreshes are being processed for. After a refresh has been processed it will be automatically removed from this table. The below SQL examples also include the SQL statements for seeing these refreshes in processing within the table.

Refresh An Individual User

EXECUTE ELEOS.usp_AddUserRefreshRequest 'DRIVERNAME'
SELECT * FROM ELEOS.UserRefreshRequests WHERE Username = 'DRIVERNAME'

In this example the SQL executes the procedure, passing in the single user ‘KUSBEN’ to trigger a refresh for that user. The results shown immediately after executing the procedure are from the SELECT statement which shows the refresh in processing for the ‘KUSBEN’ user.

A use case for refreshing an individual user can be when changes to the Driver’s trip must display the updates on the Loads Placards immediately. Using a database trigger or a scheduled process to call the EXECUTE statement at the end of the trip updates process, and passing in a username variable would result in a refresh to occur in response to changes on a user’s trip. This can help ensure the application is refreshed and shows the trip changes even if the user was not touching the application and sitting on their dashboard.

Having this called at the end of an existing SQL process would look like the following highlighted in red:

Refresh Team Users

EXECUTE ELEOS.usp_AddUserRefreshRequest 'TEAM:TEAMNAME'
SELECT * FROM ELEOS.UserRefreshRequests

In this example the SQL executes the procedure, passing in the team ‘TEAM:EASTCT’ to trigger a refresh for that team. It should be noted that teams should be passed in using the prefix ‘TEAM:’ appended with the actual team in this case being ‘EASTCT’. The results shown immediately after executing the procedure are from the SELECT statement showing all refreshes in processing. In the above test example, the ‘EASTCT’ team consists of only users KUSBEN and PURJAC.

A use case for refreshing a TEAM can be when making a change to a team’s dashboard in App Manager for training reminders and deadlines that are upcoming.

Refresh Terminal Users

EXECUTE ELEOS.usp_AddUserRefreshRequest 'TERM:TERMINALNAME'
SELECT * FROM ELEOS.UserRefreshRequests

In this example the SQL executes the procedure, passing in the terminal ‘TERM:SCOBEL’ to trigger a refresh for that terminal. It should be similarly noted that terminals should also be passed in using the appropriate prefix ‘TERM:’ appended with the actual terminal name in this case being ‘SCOBEL’. The results shown immediately after executing the procedure are from the SELECT statement showing all refreshes in processing. In the above test example, the ‘SCOBEL’ terminal consists of users KUSBEN, PURJAC, and APPSCO.

Drivers that are part of a certain terminal can derive benefit from a refresh immediately when there are adverse weather conditions and a no travel zone alert.

Refresh All Drivers

EXECUTE ELEOS.usp_AddUserRefreshRequest 'ALLDRIVERS'
SELECT * FROM ELEOS.UserRefreshRequests

In the final example the SQL executes the procedure passing in the specific parameter ‘ALLDRIVERS’ to trigger a refresh for every driver. For this refresh the exact parameter ‘ALLDRIVERS’ should be used. The results shown immediately after executing the procedure are from the SELECT statement showing all refreshing in processing for all drivers.

Refreshing all drivers should be used for changes that affect everyone. This could be used for important news that should be relayed to every driver (in increments of 300 per 5 minutes).

Triggering User Refresh For Different Divisions

User Refresh also allows the ability to refresh the application across multiple divisions when configured. If you are structured to run multiple divisions from Eleos, you can update the additional setting within your appsettings.json file where your integration is deployed. This setting is also found under the general “Settings” section and is the “AdditionalUserRefreshDivisions” setting:

Note: When configuring additional divisions to allow refreshes for, you will need to include within the brackets as shown above, the division code -> followed by a colon -> then the API key of the additional Eleos division as demonstrated with the example { “asr”: “eleos_abcdefghijklmnopqrstuvwxyz123” }.

Once the additional divisions are configured, you can then specify the division code when executing the ELEOS.usp_AddUserRefreshRequest procedure, passing in the driver and division you want to trigger a refresh for.

Refresh User In Specific Division

EXECUTE ELEOS.usp_AddUserRefreshRequest 'DRIVERNAME', 'divisioncode'
SELECT * FROM ELEOS.UserRefreshRequests WHERE Username = 'DRIVERNAME'

The example screenshot below shows triggering a refresh for the ‘KUSBEN’ driver in the “asr” division:

Note how the DivisionCode column now contains the “asr” division that was specified.

Trigger Custom Processing When A User Refresh Is Executed

If a custom process needs to occur for user refresh requests every time the ELEOS.usp_AddUserRefreshRequest procedure is called, additional scripting can be altered within a sub-procedure called ELEOS.usp_AddUserRefreshRequest_Custom which is ran at the end of ELEOS.usp_AddUserRefreshRequest. This sub-procedure has access to the user refresh requests before they are inserted into the ELEOS.UserRefreshRequests table and acted on allowing for intermediate customization. For more information on the usage of a ELEOS.usp_AddUserRefreshRequest_Custom sub-procedure see the templated version called ELEOS.usp_AddUserRefreshRequest_Custom_Template following your SQL Contracts deployment. Prior to this, changes can be made within your desired scripting without restriction.

Triggering User Refresh From An HTTPS Request

The user refresh examples from above sections can also be done through an HTTPS Request by utilizing a tool such as Postman or CURL. These HTTPS requests are not directly sent to Eleos, rather they are instead sent to an endpoint within your integration that then takes the provided parameters in the request body and executes the SQL with them like the examples shown above. Below is a template of a CURL request that shows how you would configure the request and its parameters for triggering refreshes:

curl -X POST "https://your-route-in-app-manager-service-configuration.net/refresh" \ 
  -H "Authorization: key=your-eleos-platform-key-in-app-manager-service-configuration" \ 
  -H "Content-Type: application/x-www-form-urlencoded" \ 
  --data-urlencode "username=DRIVERNAME, TEAM:NAME, TERM:NAME, ALLDRIVERS " \ 
  --data-urlencode "divisionCode=optional-additional-division-code"