 Robert Baehr | Robert Baehr November 29 2024 04:31:31 AMGreetings:
The purpose of this post is to provide an overview of JSON to provide a common ground for subsequent posts on JSON and LotusScript. See the Business Case for an overview of why this is important.
Important Terms Used Here: - Provider: This is the source of the data that will be transferred.
- Consumer: This is the target web application that will accept the data from the Provider. It is important to note that the Consumer defines the Schema of the JSON data.
- Schema: Defined by the Consumer, this is the definition of the JSON data format. The Provider must obtain the the Schema and understand it in order to process the data correctly and completely.
For starters, consider the following Domino document that will be used for reference. | Domino Field Name | Value(s) | Notes | | vehicleType | CAR | A single valued text field | | vehicleColorOptions | RED
BLUE
GREEN | A multi-valued text field | | vehicleStyle | TWO DOOR
FOUR DOOR | A multi-valued text field | | vehicleReleaseDate | 01/01/2024 | A date/time field |
WHAT IS JSON:
JSON is an acronym for JavaScript Object Notation. It is a standard which permits the transfer of data from a host system (the provider) to a target system (the consumer) over HTTP/S. Therefore, it is typically found in web applications. The "JavaScript" in JSON is merely because the structure of JSON resembles the syntax of JavaScript. That's where the similarities end.
The biggest takeaway is that the consumer 'defines' the JSON schema. Before diving into JSON, make sure that the consumer documents their schema, for if there is a mismatch between what the provider sends and the consumer expects, failure will result.
The NAVIGATOR:
Like the Domino form acts as a container for a single record (document) of data, the Navigator is the container for a JSON record. The definition of a Navigator is the open and closed squiggly brackets ( {} ), as shown below:
{
<>
}
NAME/VALUE PAIRS:
Each construct in JSON is made of of name/value pairs, where the name and the value are separated by a colon ( : ), as shown below.
"name" : "value"
It is important to understand that the "value" of a name/value par can be any standard data type (strung, number, boolean, date, etc.). It can also be a JSON Object or JSON Array (covered later).
Multiple name/value pairs are separated by a comma ( , ), which is short for "but wait, there's more data to process". The exception is the last name/value pair - it does not end with a comma because there is no more data to process.
For example, using the Domino document above, we can view this data in JSON format, as shown: | Start the Navigator: | | { | | Add a Name/Value Pair "vehicleType" with the value of "CAR". Note the trailing comma - there are more Name/Value Pairs to process: | | "vehicleType" : "CAR", | | Add a Name/Value Pair "vehicleColorOptions" with the value of "BLUE". Note the absence of a trailing comma - there are no more Name/Value Pairs to process: | | "vehicleColorOptions" : "BLUE" | | End the navigator: | | } |
JSON OBJECTS:
A JSON object is a name/value pair whose data comprises of one or more constructs enclosed in squiggly brackets ( {} ). In its simplest form, an Object is defined as follows:
"objectName" : { <> }
Returning to the sample Domino document, the following could represent the vehicleStyle field: | Start the Navigator: | | { | | Add a Name/Value Pair "vehicleType" with the value of "CAR". Note the trailing comma - there are more Name/Value Pairs to process: | | "vehicleType" : "CAR", | | Add a Name/Value Pair "vehicleColorOptions" with the value of "BLUE". Note the trailing comma - there are more Name/Value Pairs to process: | | "vehicleColorOptions" : "BLUE" , | | Add a Name/Value pair "vehicleStyle" that is an object containing two Name/Value pairs as members. Note that "coupe" has a trailing comma, while "sedan" does not: | | "vehicleStyle" :
{
"coupe" : "TWO DOOR",
"sedan" : "FOUR DOOR"
} | | End the navigator: | | } |
JSON ARRAYS:
A JSON Array is a name/value pair whose data comprises of one or more constructs enclosed in square brackets ( [] ). In its simplest form, an Array is defined as follows:
"arrayName" : [ <> ]
Returning to the sample Domino document, the following could represent the vehicleColor field: | Start the Navigator: | | { | | Add a Name/Value Pair "vehicleType" with the value of "CAR". Note the trailing comma - there are more Name/Value Pairs to process: | | "vehicleType" : "CAR", | | Add a Name/Value Pair "vehicleColorOptions" that is an array with the values of "BLUE","RED","GREEN". Note the trailing comma after BLUE and RED, but none after GREEN. There is one after the ], because there are more name/value pairs to process: | | "vehicleColorOptions" :
]
"BLUE",
"RED",
"GREEN
], | | Add a Name/Value pair "vehicleStyle" that is an object containing two Name/Value pairs as members. Note that "coupe" has a trailing comma, while "sedan" does not: | | "vehicleStyle" :
{
"coupe" : "TWO DOOR",
"sedan" : "FOUR DOOR"
} | | End the navigator: | | } |
HOW TO CONSTRUCT THE JSON DATA RECORD:
Imagine having to create these constructs from scratch, keeping track of every squiggly bracket, square bracket, and comma. While it has been done, it can be time consuming, frustrating, and, depending on the Schema definition, just short of a nightmare.
That's were the LotusScript JSON classes come in - they allow you to construct JSON data records while doing all the housekeeping for you.
SUMMARY:
I hope that "JSON and LotusScript: The Basics" was useful. Now it is time to move on to the next part in this series - "JSON and LotusScript: The JSON Navigator".
Cheers!
Robert Baehr
The Unofficial Poster Child for Notes and Domino Robert Baehr November 29 2024 02:57:04 AMGreetings:
I am not sure if anyone has had a true business need to use the LotusScript JSON classes, so I thought I'd share one that was a challenge (and fun) to be involved with.
Business Case:
A customer (provider) has a requirement to transfer more than 1000 Domino documents to a global organization (consumer). The requirement of the consumer was that all data be provided in JSON format, and, to their exact specifications. An overview of the requirements is shown below:
As an added bonus, the Domino documents are inter-related, so some fancy footwork was needed to get the data into the consumer-required JSON format.
I decided to design a solution using Domino (duh!), the LotusScript JSON classes, and the LotusScript REST API as the foundation of the solution. While still in the data verification phase, the solution is functional and fast!
I'll be posting a series of articles here which will outline my journey through the process, and explain the in-and-out of the JSON classes. Given the confidentiality of the data in question, I'll be using a sample database to explain the process. I'll also be starting slow, providing an overview of JSON to form a "common ground".
Of, the fun lies ahead!
More to come - stay tuned!
Cheers!
Robert Baehr
The Unofficial Poster Child for Notes and Domino Robert Baehr November 24 2024 05:05:29 AMGreetings:
My apologies for being gone for a while. The last few years have been pretty hectic. Two states, three jobs - I'm sure you can understand.
I am back, and, ready to share some excellent experiences I have had with HCL Notes and Domino, especially the LotusScript JSON classes, REST API. I am preparing what (is now) a ten part series covering JSON/REST to share with you soon. I'll also be dropping some tidbits in the area of cyber security.
I'll be getting this train rollin' within the next week. Your patience is appreciated.
Hope all are great!
Cheers!
Robert Baehr
The Unofficial Poster Child for HCL Notes and Domino Robert Baehr April 26 2023 02:13:57 AMGreetings: I am up to my eyeballs in cloud migration, and have not had a ton of time to spend on Domino lately. Toss in a little PowerApps and the hits just keep on coming. Am learning a lot, and enjoying the experience. One Domino item I have been tinkering with is the integration of docuSign with Domino. So far, minimal success due to time I am able to spend on a customizable app for docuSign / Domino data integration (but, I have the basics, so I have that going for me). Anyone see a need for integrating docuSign and Domino? Hope all are well! Cheers! Robert Baehr The Unofficial Poster Child for Notes and Domino Robert Baehr November 12 2022 06:38:02 AMGreetings: First, I am fine. Really. In a rainy, under-caffeinated morning, I decided to write about "life planning". Have you done it? If not, you might want to consider getting organized. I took some time and wrote an app using Domino for the NOMAD mobile client to coordinate all of the information that my wife will need in the even that I am hit by a meteor, truck, or just plain drop dead. I call me "My Death App", and, since I'll likely be with Domino "'til the end", it seemed fitting to develop the application on the Domino platform. I know people who have their life in a password-encrypted spreadsheet. Well, My Death App has the benefits of data encrypted in transit, at rest, and no data will be on the mobile device (and can't be). While nothing is 1000% secure, this information has to be stored somewhere, and I'm banking on Domino to keep it secure. Domino will take me to (or put me in) the grave anyway, so I figured - what the heck! Cheers! Bob Baehr The Unofficial Poster Child for Notes and Domino Robert Baehr July 2 2022 04:03:36 AMGreetings: A company (Client) uses HCL Notes and Domino to capture and create reports on various elements. By rule, this data must be shared with a global organization (Vendor) within a fixed time-frame for tracking purposes and quality control. If data is submitted late, then the Client could lose its business partnership with Vendor (not good). The Vendor designed a new system which requires Client to submit all data in JSON format. Since the original applications were not designed to export data in JSON, and data comes from multiple NSF files, I devised the following solution using Notes and the JSON classes in Lotusscript. The scripts include conversion of data (dates, for example) and packaging of the data as per the JSON data model and structure supplied by the Vendor.  This was frustrating to build, for the Vendor system was new and changes made on the Vendor system - causing me to revisit my new app and make adjustments therein. In the end, I look back and think.... THIS WAS A BLAST TO BUILD!!!!!! Thought I'd share a brief, real world application of Notes, Domino, and the Lotusscript JSON classes. Cheers! Robert Baehr The Unofficial Poster Child for Notes and Domino Robert Baehr January 19 2022 02:19:50 AMGreetings:
Given that everyone is on the cloud migration bandwagon, I thought I'd share a little simple "trick" that I use to map a network drive to my OneDrive (note: This works for Google Drive with some slight modification).
While there are some other methods that I have found on-line, many appear cumbersome and, quite frankly, I could not get any of them to work. Keeping in mind that all environments are different, I took the following approach that should work for any Windows client environment.
Instead of using the "Map Network Drive" option of Windows Explorer, I reverted back to my old DOS days and utilized the SUBST Command. For those brought up in a post-DOS world, SUBST works like NET USE - it assigns a drive letter to a local folder on your PC. The base syntax is:
SUBST L: "Path", where - L: is the drive letter you want to use
- "Path" is the local folder that you want to map the L: drive to
When you specify "Path", don't forget the double quotes.
For my example, from a DOS prompt (there's that DOS word again), I mapped the Z: Drive to my OneDrive folder by issuing the following command:
SUBST Z: "%USERPROFILE%\OneDrive"
That's it! If I look in explorer, I see a Z: drive. If I am logged into OneDrive, any files added, deleted, or modified therein will sync to the cloud.
For ease of management, this command can be placed in a login (or other) script so that users have a familiar drive letter in which to reference their OneDrive files.
Hope someone finds this useful - I know I do!
Cheers!
Robert Baehr
The Unofficial Poster Child For Notes and Domino
Robert Baehr September 27 2021 04:56:59 AMGreetings: My SSL/TLS Certificates were due to expire, so I thought - what the heck - let's try the new CertMgr feature of Domino 12. I mean, what could possibly go wrong? Answer: Nothing! In case you haven't read about it yet, Domino 12 includes full integration with (and a lot of automation to) the Let's Encrypt free SSL/TLS certificate authority. I decided to start off with a cup of coffee - a little cream - a dash of splenda - and the Domino Administrator help database. After a quick NOTES.INI modification, and server restart, I entered the CertMgr.nsf database on my server. After completing two simple forms, and submitting my request, I was amazed that the SSL/TLS certificates that I requested were fully operational. I mean, I barely got to sip my coffee before the process was completed. No KYR - no STH files to deal with. No KYRTOOL and OpenSSL tools needed. No copy - no paste - no "retrieve certificate" needed. Thank you, HCL, for taking a cumbersome process and making it easy. It's the little things..... Now, where's the rest of that hot coffee? Cheers! Bob Baehr The Unofficial Poster Child for Notes and Domino. Robert Baehr September 6 2021 07:28:17 AMGreetings: "What does Domino R12 and ONE Cup Of Coffee Have In Common"? First, if you know me, then you know I love my coffee. Simple - a little cream, a little sweetener - and I am a happy man. Second, if you know me, then you know I love Domino (I didn't get "The Unofficial Poster Child for Notes and Domino" title for nothing). So, what's the point? This morning, I woke up and decided to upgrade two Domino servers from R11 to R12. Now, I didn't enable any of the new R12 features (yet), but just to get the servers upgraded. So, I made a cup of coffee, went into my office, and started the process. From download to INI "tweaks" to completing the upgrade of two servers took less time than it took for me to finish one cup of coffee. Yes - the process was that quick - that painless - and everything works as it did before (mail, apps, web). In a word, flawless. And my coffee was still quite hot when done. Try THAT with a 'competitive' product! As a customer, I really appreciate the efficiency of the upgrade process. Hats off to HCL - well done! Next up, since I have the CCB license, I am going to consolidate the servers. I have the consolidation plan done, and I think this may actually take TWO cups of coffee. How can I get any happier than that? Happy Computing! Bob Baehr The Unofficial Poster Child for Notes and Domino Robert Baehr July 11 2021 02:45:38 AMGreetings: I am seeking information on bi-directional data transfer between Adobe PDF forms and Domino. Mail aside, are there any Domino apps that have the ability to: - take data from a PDF form and create a document in a Domino application? - take data from a Domino application and automatically populate an Acrobat form? Of course, there would be "customization" involved (mapping PDF fields to Domino fields, PDF forms to Domino documents, etc.) Thoughts appreciated. Happy Computing! Robert Baehr The Unofficial Poster Child for Notes and Domino |
|