Genii Weblog


Civility in critiquing the ideas of others is no vice. Rudeness in defending your own ideas is no virtue.


Mon 14 Sep 2020, 03:15 PM
 
Inline JPEG image
 
 
With Exciton Boost out this week, I thought I'd spend a little time explaining some of its features and some comparisons with Domino Access Services. Today, I'll talk about Agents, both explicit and implicit (or "secret"). This is a lengthy post, but very important as it outlines a key differentiator for Exciton Boost which makes the product more useful for real business needs for flexibility, security, and data integrity.
 
  • Key Concept: Application Control and Flow belong to the client, but Business Logic and responsibility for Data Integrity and Security belong to the server
  • Differentiator: Exciton Boost allows client apps to call business logic on server via agents, but also enables server logic to override and control data access and updates
A common complaint by those who have tried Domino Access Services is that it treats Domino as nothing more that a simple data store. While you can read/write data to the data store, this ignores Domino's strengths and sometimes requires too much data and business to be handled on the client when it would be better staying on the server.
 
Exciton Boost treats Domino as a partner in applications, allowing most application logic and flow to be carried out in the mobile or web app, but also empowering business logic and data integrity to be handled out on the server where appropriate., If you take a look back at the video from my post, RPC - Empowering the server while retrieving to the client, you'll notice that the thousands of medical terms and links did not need to be downloaded to the client, but remained on the server where a simple JSON-RPC call could use them. The application triggered the call, but the processing happened on the server where much of the data resides. Agents take this concept a step further.
 
In traditional Domino applications, business logic is often built into agents which may in turn call script libraries. Exciton Boot harnesses these agents at several stages from both the REST API or JSON-RPC API.
 
 
Query Save agents called explicitly from the REST API
 
In Domino Access Services, using POST to create and PUT/PATCH to update allows you to set field values (with some limitations), plus you can use compute with form to validate fields, but only by request of the client application.  This poses some security issues. At best, an agent in the database could process the document after the fact by running on a schedule, but the documents are saved first.
 
In Exciton Boost, both the client and server may specify agents to be run on documents being created, updated or deleted using the REST API in Exciton Boost. These agents happen BEFORE the document is updated, thus preventing even short intervals when data integrity might be a problem. For example, using POST to create a document, or PUT/PATCH to update a document, the app can add
 
"@querysave": true
 
to the JSON payload to trigger the WebQuerySave agent specified for that form. Even greater control can be exerted by specifying the agent to be run as a query save agent.
 
"@querysave": "Validate Order"
 
Either the form's WebQuerySave agent or the "Validate Order" agent is run on the document before it is saved. If the SaveOptions item is set to "0", the update will not occur, allowing existing WebQuerySave agents to be used. Note: one difference is that the SaveOptions field does not need to already exist as it does with traditional WebQuerySave agents.
 
You may also set the query save agent using the X-Query-Save header in cases where that is easier.
 
X-Query-Save: true
 
or
 
X-Query-Save: Validate Order
 
 
Query Save agents called implicitly from the REST API (aka "secret agents")
 
With Exciton Boost, while the client application is in control of the query save agent above, there is a second layer of query save agent controlled by the Exciton Configuration. When a document is to be updated via the Exciton REST API, the database or form may have a designated query open or query save agent. This empowers the server to add, delete or modify any items including the Form, and to set the SaveOptions item itself if desired. The ultimate responsibility and control remains on the server.
 
 
Query Open agents called explicitly from the REST API
 
Because there is no JSON payload in a GET, a query open agent is always specified via the X-Query-Open header. The form's WebQueryOpen agent can also be run using the URL parameter &queryopen=true.
 
X-Query-Open: true
 
or
 
X-Query-Open: Prepare Order for REST use
 
 
Query Open agents called implicitly from the REST API
 
Similar to the query save, Exciton Boost allows the server to specify a Query Open just for documents retrieved using the REST API. When a document is to be opened via the Exciton REST API, the database is checked for an agent denoted by the form. For a Main Topic form, the agent would be called "(QO-Main Topic)", or "(QO Default)" if no agent was found for that form. If the agent exists, it is run before any client-specified query open agent. This empowers the server to add, delete or modify any items before the document is rendered. The ultimate responsibility and control for what data is accessed remains on the server.
 
 
Agents called explicitly from the JSON-RPC API
 
With Exciton Boost's JSON-RPC API, calling agents is as simple as
 
{"jsonrpc": "2.0", "method": "db.runAgent", "params":["Agent to run"]}
 
or
 
{"jsonrpc": "2.0", "method": "doc.runAgent", "params":["Agent to run"]}
 
or
 
{"jsonrpc": "2.0", "method": "coll.runAgent", "params":["Agent to run"]}
 
These would all run the same agent, but the first would have no documents selected (and so should be an agent which does not expect documents selected), while the second would run on the current document without saving it, and the third would run on all of the documents in the document collection, saving them if appropriate. If an id is specified, the print statements returned from the agent would be returned as the result.
 
Request (using POST): {"jsonrpc": "2.0", "method": "db.runAgent", "params":["Agent to run"], "id": 1}
 
Response (with 200 OK): {"jsonrpc": "2.0", "result": "Agent run successfully with 214 documents found", "id": 1}
 
 
Query Save agents called implicitly from the REST API (aka "secret agents")
 
Exciton Boost uses the same query save agents for documents to be updated via JSON-RPC as for those updated via REST API, thus allowing consistent responsibility and control to remain with the server.
 
 
==> Request a free Exciton Boost evaluation license, and we'll send you the license and a link to the software as soon as it is released. <==
 
 

Copyright © 2020 Genii Software Ltd.

Tags: