KBA-01759 Validation and Document Logic Overview


How do ATC Workflow and Save Extensions interact? 
Can I use both ATC Workflow and Save Extensions?
I want to add some validations.  Where do I do that?


sfPMS was designed as an extensible event-driven system. It is certainly possible to extend the system in multiple layers. Doing so requires some understanding of how the layers interact. While there is the possibility for unintended outcomes, there is also great potential for ROI.

Application Layers

The primary layers in the application include the Presentation, Business Logic and Data layers.

HTML Presentation Layer (UI/UX)

Sometimes called the “front end”: What the user sees and interacts with in their browser/device. You extend this layer using JavaScript that can take advantage of jQuery and sfPMS API.

PROS: Your extensions to the user interface have the highest ROI for affecting the user experience and providing feedback on validation and business rules. It is very easy to communicate with the user.

CONS: This layer is weakest at enforcing and guaranteeing business rules. Of note: validations can be bypassed and should be repeated at a lower layer.

This layer can make requests to the Business Logic Layer via asynchronous calls or page post back events. For example, the request to run a workflow script by name is a post back event as is a click-on-the-save button. JavaScript processing on the page is suspended during post backs.

Business Logic Workflow Script Layer

When a user request causes a post back to the web application server and the request requires the document to create or save a document, then additional workflow scripts events can enforce some business rules, including validations. As mentioned, the Presentation layer can also explicitly call a workflow script. Once workflow begins, the workflow can cause the current document or other documents to be loaded, created, and saved. Each of those actions can cascade its own series of workflows. This is intended. Workflow can conditionally suppress events, but the reality is that nested workflow events are typically beneficial.

With Version 2023 and later, REST API calls invoke this layer.  REST API calls will trigger workflow as appropriate.

PROS: Workflows can be defined to run during various times in the document life cycle (create, normal saves, pending saves, approval, route events).

CONS: While workflow can display messages to the user, these messages are typically “separated” by a post back action, making them less connected to the causal issue for the user. The workflow language is proprietary and limited in scope. There is no debugger. Workflow can nest and cause infinite loops.

Data Layer: SQL Transaction Extensions

Technically, this layer continues and provides durability to the Business Logic Layer, making things permanent. When a document save transaction is performed you can inject SQL logic into the transaction. See KBA-01183

PROS: Extremely fast, fully ACID (atomic, consistent, isolated and durable).

CONS: Must be coded in TSQL and are difficult to deploy. Very limited in communication back to the user. Basically can only display a message if the save transaction is also blocked/terminated.

Interactions between Layers

The Presentation Layer can make requests of the Business Logic layer, including explicitly running a named workflow script. Some requests pass through the Business Logic layer to the Data layer to read or update data elements.

Similarly, the Business Logic layer exercises the Data layer. It can also call JavaScript or push messages back to the user. These messages can be performed even if the save was fully committed.

The Data layer is the back-end and foundation. It can send a message back in the form of a processing exception. It can also stick data into a field that might be read by Workflow or Presentation layer; however, this requires code in those layers to fetch the “message” and take some sort of action.

If you try and visualize this as first-second-third, then the Presentation Layer is first, the Business Logic and its workflows are second, followed by the Data layer (and its save extensions) are third.  This becomes muddied as workflow can include commands that nest the layers, such as ATC: COPY, or even ATC: SAVE.  During an ATC: SAVE any workflow scripts and save extensions associated with the document being saved will fire and then return to the current workflow script.

Whence Validation?

It is a reality that validation is something that must be handled more than once.

From a usability (UX) perspective, the Presentation layer is a must for validations. You can let the user know in real time that something is not going to be allowed. Validations here feel responsive instead of intrusive.

Unfortunately, the reality is that these validations are not going to cut it if your end goal is data integrity. Even if you can write perfect code that handles every permutation of field order and DOM event cascading, you cannot test your code on every browser (IE, Safari, Chrome, Firefox, Samsung). You cannot even test your code on every release of Chrome, which is updated monthly without your permission.   And finally, REST API calls skip the presentation layer entirely.   To be effective, a validation must also be performed in the Business Logic or Data layer.