Genii Weblog

Exciton Boost - Formula(s) for success

Tue 15 Sep 2020, 11:18 AM

by Ben Langhinrichs
Inline JPEG image
With Exciton Boost out this week, I'm spending the week talking about its features and some comparisons with Domino Access Services. Today, I'll talk about formulas, specifically Notes formula language, and how access to formula evaluation can empower your mobile and web apps in both the REST API and JSON-RPC API.
  • Key Concept One: Not all information is available to the client, nor should it be,
  • Differentiator One: Exciton Boost allows client apps to express values as Notes formulas, and allow the Domino server to evaluate and use the data which the client doesn't have.
  • Key Concept Two: Some operations require intermediate results, but should not trigger repeated saves or repeated calls back and forth from the client and server,
  • Differentiator Two: Exciton Boost allows intermediate results to be stored and then retrieved using Notes formulas
Because the API in Domino Access Services treats Domino as a simple data store, calculations usually require data to be brought back to the client. If this means intermediate results, it requires multiple requests which is both inefficient and leaves the document on the server in a partially updated state for too long.
Setting field values in REST API using formulas
In Domino Access Services, using POST to create and PUT/PATCH to update, field values must be known to the client and expressed explicitly. Alternatively, the form must contain all the fixed formulas and must be evaluated to get the results, which is less flexible.
In Exciton Boost, field values may be set directly or evaluated by a server-side formula. Let's look at an example where we want the request to reflect the abbreviated, not common, name of the logged in user, and we don't want to have to modify the request payload. In the first line below, we only know the name used to log in, and we have to alter the payload to ensure it is used. In the second line, we let the server evaluate the formula to determine the abbreviated name, which it does know.
Explicit => "Requestor": "Ben Langhinrichs"
Formula => "Requestor": {"@evaluate": "@Name([Abbrev]; @UserName)"}
Another example might be where an item number is known, but we want to use the item name. This requires a lookup to another database. 
"ItemNo": "REDM01",
"ItemDescr": {"@evaluate": "@DbLookup(\"\"; \"\":\"Orders.nsf\"; \"(ItemLU)\"; ItemNo; 2)"}
In this example, the ItemNo is saved as a value on the document, and is also used as an intermediate value in the formula for ItemDescr. If you retrieved the document afterwards, the values would be returned as
"ItemNo": "REDM01",
"ItemDescr": "Redmond Real Salt - Ancient Fine Sea Salt, Unrefined"
For those worried about opening up the power of @DbLookup and so forth, we are putting various controls in place to make sure they are not used to access data which is off limits, above and beyond the control based on Domino security.
Setting parameter values in JSON-RPC API using formulas
In Exciton Boost's JSON-RPC API, methods are called with specified parameters. Let's use the example from yesterday with agents. 
Request (using POST): 
{"jsonrpc": "2.0", "method": "doc.runAgent", "params": {"@evaluate": "@If(SalesTotal >= SalesTarget; \"Reward profitability\"; \"Punish failure\")"}, "id": "msg"}
Response (with 200 OK):
{"jsonrpc": "2.0", "result": "Loser! You missed your sales target. No soup for you!", "id": "msg"}
Different agents were run depending on whether the SalesTotal was greater than the SalesTarget, though the client never needs to know what either value is. The return value in the response is the output, if any, from Print statements in the agent. I use it here to send a message.
Another example is where we have a batch of RPC calls. By setting a url paramater, we can specify that return values with string ids be saved as intermediate field values. We are running this on the Body field of a specific document.
{"jsonrpc":"2.0", "method":"rtc.getCount", "params": "Graphic", "id": "ImageCount"}, 
{"jsonrpc":"2.0", "method":"rtc.getCount", "params": "Doclink", "id": "DoclinkCount"}, 
{"jsonrpc":"2.0", "method":"rtc.appendTable", "params": [1, 2, "", {"@evaluate":"\"Doclinks: \"+DoclinkCount"}, {"@evaluate":"\"Images: \"+ImageCount"}]}
The first two calls use Exciton Boost methods to get the number of images and doclinks in the Body field, and saved in numeric fields called ImageCount and DoclinkCount. Then, we append a table at the end of the Body field with one row and two columns. The values of the columns show the number of doclinks and images, using those intermediate fields from the document. 
These are fairly simple examples, but they show how powerful formula evaluation can be, and how intermediate results allow a series of actions based on earlier actions.
==> 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.

What has been said:

No documents found

Have your say:

Name *:
e-mail addresses will not be displayed on this site
Comment *:

<HTML is not allowed>
Linking: Add links as {{http://xxx|title}}, and they will be activated once approved
Blocked? Unable to post a comment? Please read this for a possible explanation...