Before Starting

Please note that Server-Side Validation will ONLY work for Actions being performed within the Loadlist, marked as a "Workflow Action" within the Eleos Platform. Server-Side Validation will NOT work for an Action executed from anywhere else within the application such as the Dashboard, Menu, and Messaging.


Introduction

The Server-side validation of messages is a feature of Eleos that allows users to submit requests to validate workflow messages and inform the driver if a field on a form is valid before the submission of the message. There are 3 main steps in validating a message that will be discussed in more detail in the sections below, and those are: 1) allowing a form to be validated, 2) returning a response based on the validity of the form, and 3) the delivery of the final validated message. Server-side validation can only be utilized in workflow messages.


Server-Side Validation Responses

As of version 1.52, Eleos allows our web service to receive validation requests during workflow actions. This allows us to validate fields inside of the workflow action to ensure that the data entered by the driver is valid before submitting the form. If our Server-side validation logic determines that one of the fields that a driver entered is invalid, we will return an HTTP response code of 422, meaning Unprocessable Entity, along with the fields that are determined as invalid. If we determine that the fields of a form are valid, we return a 200 OK, which tells Eleos to resend the message with a “validation_status” of “validated”, meaning this is the final version of the message.

Response Code of 422, Unprocessable Entity

This means that one or more of the fields entered by the driver is considered invalid by our ELEOS.usp_ValidateMessage procedure, and the driver will be prompted to resubmit the form after editing the fields that are returned as part of the response. We do not audit or process any messages that are considered validation requests. For example:

 a. If a driver submits a form that we consider invalid, as part of the 422 response we send to Eleos, we include the field codes and error messages that are populated inside our stored procedure.  To customize the error messages and when they are returned, modifications can be made using ELEOS.usp_ValidateMessage_Custom_Template, and more information on where to make this modification can be found within the template itself:  

Note: If  ELEOS.usp_ValidateMessage_Custom_Template  does not exist, this indicates that SQL contracts have not been implemented, and the modifications would be made to ELEOS.usp_ValidateMessage instead. 


Below is an example of field codes and error messages returned:


 b. When this happens, in the application the driver will see error messages like the one in the screenshot below. These errors correspond to the fields returned in the 422, and the error message for those fields.


Response Code of 200 OK

If the integration responds with a 200 OK when making a sever validation request, this means that the fields of the form have been validated against the ELEOS.usp_ValidateMessage procedure, and has no issues reported. This form is considered valid to us.

  1. After we send a response of 200 OK to Eleos, Eleos will send us the “final” message with a “validation_status” of “validated”, which will be audited and processed like a normal workflow message. 
  2. The integration only returns a 200 OK if there are no results returned from the ELEOS.usp_ValidateMessage procedure, meaning that no errors were returned from the procedure. 


Enabling Server-side Validation

Workflow Actions

To enable Server-Side Validation on workflow actions, we will need to make Drive Axle actions changes, along with SQL side changes, to add the form that you are validating to the ELEOS.usp_ValidateMessage_Custom_Template procedure. Both of the following steps will need to be completed, or the message will not be validated on the server side. You can only enable server-side validation on workflow actions sent through the Eleos platform; other types of messages cannot be validated.

Drive Axle Actions

  1. To enable validation of workflow forms, the first thing you will need to do is log into your Drive Axle environment. After logging in, navigate to the App Manager. Inside the App Configuration dropdown, click on “Actions” as highlighted in the below screenshot.  
     
  2. Find the workflow action that takes you to the form that you are wanting to validate. For example, if you wanted to add Server-Side Validation to the WORKFLOW-START form, find the action that takes you to that form. You can find the form that an action links to on the left side of the screen after clicking on an action, under the “Form” section. You can find an example of this highlighted in yellow in the following screenshot:
     
  3. Click on the check box next to “Server Validation?” on the action, highlighted in green in the screenshot above. This will allow Eleos to send us the “server_validation_status” and “server_validation_request” properties for this action and allow the integration to attempt to validate the form.

ELEOS.usp_ValidateMessage_Custom_Template Procedure

To validate fields in a specific workflow form, you will need to modify the ELEOS.usp_ValidateMessage_Custom_Template procedure inside SQL. The custom procedure has instructions on how to make modifications:

The ELEOS.usp_ValidateMessage_Custom_Template also has an example of how to read and validate a particular field on a form:

Note: If you validate a field that doesn’t exist on the form, it will prevent the driver from correcting the error and not allow workflow to continue. Please ensure that fields you are attempting to validate exist on the form.


If SQL Contracts are Not Implemented

If ELEOS.usp_ValidateMessage_Custom_Template does not exist in the database, this indicates that SQL contracts are not implemented, and instead modifications will have to be made to ELEOS.usp_ValidateMessage by following these steps: 

  1. Connect to the SQL database. If you are attempting to make these changes inside the dev environment, connect to the dev database. If you are making these changes in a production environment, connect to the production database. 
  2. Expand “Programmability, right click on Stored Procedures, and click “Filter”. Add a filter for the “ELEOS” schema to narrow down the stored procedures you may have deployed.
  3. Find the stored procedure “ELEOS.usp_ValidateMessage, right click on it, and click “Modify”.
  4. This will open the ELEOS.usp_ValidateMessage procedure. After it opens, scroll down to find the declaration of the @Fields table. If a field on the form you want to verify is missing from this table, make sure to add it in this declaration statement in the same way the other fields were added. 

     
  5. Use the WORKFLOW-START form validation template as a reference for how to validate individual forms. You will want to add a section for if the form code passed in matches the form code you want to validate, and if it does, add logic to validate the fields of the workflow message. For example, if you want to validate that the Planned Trailer matches what the driver entered in, you will need something like what’s in the template for WORKFLOW-START.
  6. Ensure that the field you are validating is declared inside the @Fields table, and that the error message for the field is being inserted into the correct field. For example, if you wanted an error message to occur for the field “LOAD-NUMBER”, you would declare a “LOAD-NUMBER” field into the @Fields table and insert an error message (for example, "Load number doesn’t match current load”) into that field after checking against the form code.

If you follow both steps above, clicking the “Server Validation?” check box for the Drive Axle action, and then populating an error in the @Fields table for that value, it should allow you to validate fields being entered by drivers before the form is submitted.

Note: If you validate a field that doesn’t exist on the form, it will prevent the driver from correcting the error, and not allow workflow to continue. Please ensure that fields you are attempting to validate exist on the form.


Final Message Delivery After Validation

If a message is sent with a “server_validation_request” value of “true”, we will validate the message like the steps above, and return either a 200 OK, meaning that the message is valid, or a 422, meaning that one or more fields are invalid.


If a response of 422 is sent, the driver will be prompted with the error message for the field that was returned from the stored procedure. When the driver edits the field and resubmits the form, it will be validated again to ensure that the field has a value that is valid. 


If a response of 200 OK is sent, then it is assumed that the form is valid, and a “Final” message will be sent from Eleos that will be audited and processed. This message includes a “server_validation_status” property from Eleos and should have a value of “validated” if the message has been validated before. This is the final version of this message that will be sent by Eleos, the message will not be sent again.


More Information Regarding Server-side Validation

For more information on Server-side Validation, check out Eleos’ documentation on Server-Side Validation. You can find that at the following link: https://dev.eleostech.com/platform/#operation/upsertCustomerMessage. This link includes the message properties, along with similar information as to what’s mentioned above.