ASR Solutions

Overview

ToDos can be created in the Eleos Platform and displayed on the driver’s Dashboard, signifying that the driver needs to complete certain actions as defined in the ToDo.  ToDo items can be used to list tasks that drivers need to complete, including instructions on how to complete them and a due date. The ToDo prompts a form for drivers to fill out, where they can submit any documents necessary to complete the ToDo. This is what a ToDo placard would look like on the driver dashboard.

The following steps and examples can be used to create an expiration ToDo in the Eleos Platform and link it to the driver dashboards.

Scripting Overview  

In scripting the ToDos process starts in the configured “ToDosProcedure” in appsettings, which is the ELEOS.usp_GetToDos procedure.  ELEOS.usp_GetToDos calls ELEOS.usp_CreateToDos, and ELEOS.usp_CreateToDos calls ELEOS.usp_CreatToDoMappings which is the main mapping procedure to create ToDos from expirations mappings. Then ELEOS.usp_GetToDos_FormData is where custom properties and additional values are specified and inserted into a temp table, #ToDoData.  If a client has SQL contracts implemented, then there will be a procedure called ELEOS.usp_GetToDos_Custom_Template which is where clients would add any changes to insert custom ToDos. (Note: The subsequent sections in this document go into detail on how to make changes if SQL contracts are implemented using ELEOS.usp_GetToDos_Custom_Template, and where to make changes if SQL contracts are not implemented and the custom template does not exist.)  There are two tables that hold the data being returned: the SQL table ELEOS.ToDos, which contains the main ToDo records and their information, and the temp table #ToDoData, which holds key-value data that can be attached to those ToDos, most often to pre-fill form fields in whatever form a given ToDo''s action will launch.  

The following document goes into further detail about each procedure that creates ToDos as well as the modifications that can be made to customize ToDos.

Step 1: Create New Document Type

1. Login to the Eleos Platform.
2. Click Document Hub in the header and select App Manager.
3. Again, in the header row, select App Configuration and select Document Types from the drop down.
4. To add a new document type, scroll to the bottom.
5. Type the new document name into the Name textbox.
6. When finished, press save to update your changes.

 Step 2: Create a Corresponding Platform Form for ToDo.

1. Login to the Eleos Platform.
2. Click Document Hub in the header and select App Manager.
3. Again, in the header row, select App Configuration and then select Forms from the drop-down menu.
4. Create an Expiration Form for the ToDo you intend to add. For this example, I will use ForkLift.  Use the example screenshot on the next page as a guide to set up the Expiration form.  For document type, be sure to select the new document type you added in Step 1.

EmailTo Configuration

To configure the EmailTo for a ToDo, create a form field within the form that was created for Step 2. The new form field should have the code EmailTo.  This form can be visible or hidden from the driver.  This form field needs to exist if the form needs to be emailed to a recipient. The form should also include an EmailSubject form field to specify the subject of the email that is sent to the recipient. For more information on how to configure the form field for message forms or document forms, please see our documentation, Drive Axle - Emailing Form Data Through Drive Axle.

If SQL contracts are implemented the ELEOS.usp_GetToDos_Custom_Template should be used as a guide to modify the procedure with the scripting changes below. Eleos.usp_GetTodos_Custom_Template is the place where clients would place custom todo creation and custom form data / prefill properties. If SQL contracts are not implemented and there is no ELEOS.usp_GetToDos_Custom_Template, the values for EmailTo and EmailSubject can be specified in the ELEOS.usp_GetToDos_FormData procedure using the example scripting below. The following scripting inserts into the #ToDoData table, which holds key-value data that can be attached to those ToDos. The values are associated with the form fields for the form that was created for the ToDo so that in the application, it pre-fills form fields in whatever form is launched by a given ToDo's associated action. The following is an example of how the form data can be populated into the #ToDoData temporary table. This data will be used to create ToDos.

    ;INSERT INTO #ToDoData (

         [HandleId]

        ,[FieldName]

        ,[FieldValue]           )

    SELECT   [HandleId]         = T.[HandleId]

            ,[FieldName]        = V.[FieldName]

            ,[FieldValue]       = V.[FieldValue]

    FROM    ELEOS.ToDos T

            OUTER APPLY ( VALUES ( 'MOVE-NUMBER'     , CONVERT(VARCHAR(100), T.[MovementId]      ))

                                ,( 'ORDER-NUMBER'    , CONVERT(VARCHAR(100), T.[OrderId]         ))

                                ,( 'STOP-NUMBER'     , CONVERT(VARCHAR(100), T.[StopNumber]      ))

                                ,( 'EmailTo'         , ''                                        )

                                ,( 'EmailSubject'    , 'Demonstration To Do Message from {DriverName}'   )

                                ,( 'TODO-TITLE'      , T.[DisplayName]                           )

                                ,( 'TODO-DESCRIPTION', T.[Description]                           )

                        ) V      ( [FieldName]          , [FieldValue]                           )

    WHERE   T.[DriverId] = @p_UserName

            AND T.[Completed] = @False

    ;SET @FormattedDebugMessage = 'Populated Form Data for ToDoData for Username: ' + COALESCE(@p_UserName, '')

    ;EXEC ELEOS.usp_DebugPrint @FormattedDebugMessage

Our document Eleos - How to Determine Email Recipients for a Message has more information on how a message/form gets sent to an email.

Eleos - Report Navigation ToDo Form is one example of a ToDo that is emailed, but for the navigation issue report specifically, the address that the form is emailed to is set in the ELEOS.Settings table by setting the NavigationIssueEmailTo field value to an email address.

Step 3: Add ToDos to the Dashboard.

1. Login to the Eleos Platform.
2. Click Document Hub in the header and select App Manager.
3. Again, in the header row, select App Configuration and select Dashboard.
4. Click on the dashboard you would like to add ToDos to. If you wish to add ToDos to multiple dashboards, you will have to repeat this process for each dashboard. At the bottom, click on Add a card, and change the Type to "TODOs". Click save at the top of the page. 

Step 4: Default ToDos vs Custom ToDos.

Default ToDos Already Implemented

As a part of the TMWSuite default implementation, we have some general ToDos implemented that are useful. The default ToDos that are created come from the ELEOS.usp_CreateToDos_Mappings procedure. This procedure creates ToDos from expiration mappings and inserts them into the ELEOS.ToDos table.  It also removes ToDos that are completed. We currently have 3 categories of ToDos implemented in this stored procedure, Expiration Mappings: Driver ToDos, Tractor ToDos, and Trailer ToDos.  The ELEOS.usp_GetToDos_Custom_Template procedure is where ToDos can be created and customized, and the template itself has information and instructions on how to create and control custom ToDos.  The ELEOS.usp_GetToDos_Custom_Template procedure is a template for a custom procedure that is invoked during the process of building and retrieving ToDos that will be returned to the Eleos Platform and displayed to a user.  It offers the ability to do custom work in the response to build ToDos just before they are returned from the database, including adding new ToDos or modifying existing ones. (Note that if the ELEOS.usp_GetToDos_Custom_Template procedure does not exist, this indicates that SQL contracts are not implemented, and updates would have to be made in ELEOS.usp_ToDos_Custom instead.)

The ELEOS.ToDosMapping table contains information about expirations so that ToDos can be created for drivers from the ELEOS.usp_CreateToDos_Mappings procedure. For the ToDo to be populated for the driver, the ToDosMapping table will need to have the ExpirationType and ExpirationCode inserted to identify the expiration that the ToDo is for.  DisplayLeadDays specifies the number of days before the expiration, which is when the ToDo will display in the application for the driver. The ActionType can be one of 3 options: “scan-flow” for triggering document or photograph capture, “transaction-editor” for sending messages, or “watch-video” for watching a video. If there is a form that the driver needs to fill out, then FormCode should be the code of the associated form in Drive Axle. FormCode is required on any ToDo that requires form setup, so that would include document scans as well. If the driver needs to complete a scan to submit the ToDo, then the ScanType (document or photograph) should be specified. If the ToDo contains media from the Drive Axle Media Library, then ID of the media item (MediaId), video for example, can be specified.  If the Expiration is disabled, then Disabled can be changed to ‘1’.

For example, if you wanted drivers to complete a ToDo for their license expiring, insert the following template into the ToDosMapping table after updating the “Description” text: 

INSERT INTO ELEOS.ToDosMapping(

     ExpirationType,

     ExpirationCode,

     DisplayLeadDays,

     DisplayName,

     Description,

     ActionType,

   FormCode,

     ScanType,

     MediaId,

     Disabled                    )

 SELECT    ExpirationType        = 'DRV'

         ,ExpirationCode               = 'LIC'

         ,DisplayLeadDays           =    30

         ,DisplayName                  = 'Your License Will Expire in 30 Days.'

         ,Description                     = 'Test Description'

         ,ActionType                      = 'transaction-editor'

         ,FormCode                       = 'LICENSE-EXPIRATION'

         ,ScanType                         = NULL

         ,MediaId                           = NULL

         ,Disabled                          = 0      

Driver ToDos from Expiration Mappings

This includes any documents a driver may have that are expiring soon and are referencing the dbo.Expiration table for drivers. Any documents that are expiring soon according to the dbo.Expiration table that has not already been completed and are within the DisplayLeadDays coming from the ELEOS.ToDosMapping table will have ToDo displayed for the driver, as long as the above steps have been completed, and there is a form associated with the ToDo, and a document type for the document expiring. The ELEOS.usp_CreateToDos_Mappings procedure uses this information to create ToDos. 

Tractor ToDos from Expiration Mappings

If there are any ToDos associated with the Tractor according to the dbo.Expiration table, a ToDo will be created if the document types and forms are set up correctly. 

Trailer ToDos from Expiration Mappings

If there are any ToDos associated with the Trailer according to the dbo.Expiration table, a ToDo will be created if the document types and forms are set up correctly. Note: You will need to add the default expiration mappings to the ELEOS.ToDosMappings table for each of these default ToDos. 

Creating Custom ToDos

To create a custom ToDo for drivers to complete, you will need to complete all the DriveAxle steps above first and, you will need to add the below logic to the ELEOS.usp_GetToDos_Custom_Template procedure. (Note that if the ELEOS.usp_GetToDos_Custom_Template procedure does not exist, this indicates that SQL contracts are not implemented, and updates would have to be made in ELEOS.usp_ToDos_Custom instead, using the defaults created in the Eleos.CreateToDos_Mapping procedure as a template if you wish, as it has all the required fields for a ToDo.  The main difference between this custom procedure and the defaults is that for custom ToDos you will be inserting these values directly into the ELEOS.ToDos table.) An example template is provided below for use when adding a custom ToDo for drivers to complete:

;INSERT INTO ELEOS.ToDos (

         [ExternalSource]

        ,[ExternalId]     

        ,[DriverId]            

        ,[DisplayName]           

        ,[Description]           

        ,[ActionType]           

        ,[FormCode]             

        ,[MetaDataFormCode]    

        ,[ScanType]               

        ,[MediaId]               

        ,[Completed]           

        ,[DueDate]           )     

    SELECT   [ExternalSource]       = 'license'

            ,[ExternalId]                       = E.[exp_key]          

            ,[DriverId]                           = @p_UserName           

            ,[DisplayName]                   = 'License Expiring'           

            ,[Description]                      = 'Your license is expiring soon, please scan a picture of your license after it is renewed'           

            ,[ActionType]                      = 'scan-flow'           

            ,[FormCode]                        = '{form code}'              

            ,[MetaDataFormCode]     = '{form code}'   

            ,[ScanType]                          = 'document'              

            ,[MediaId]                            = '{id of any media items you wish to display for this ToDo}'              

            ,[Completed]                      =  0      

            ,[DueDate]                          = E.[exp_expirationdate]            

    FROM    dbo.Expiration E

    WHERE   NOT EXISTS( SELECT  NULL

                        FROM    ELEOS.ToDos T

                        WHERE   @p_UserName = T.[DriverId]

                                AND E.[exp_key] = T.[ExternalId] )

For these custom ToDos, since we are inserting directly into the ToDos table, there is no need to insert the ToDo into the ToDosMapping table. You can still add this to ELEOS.usp_GetToDos_Custom_Template to have more values to pull from during ToDo processing, but that step isn't necessary. ToDo inserts can also be added and customized for repeated use within the procedure. If done, you must ensure that the WHERE clause is updated to avoid duplicates and to only create ToDos under specific situations.  (Note that if the ELEOS.usp_GetToDos_Custom_Template procedure does not exist, this indicates that SQL contracts are not implemented, and updates would have to be made in ToDosMapping table instead.)