Hi. Troy here. Viktor has been nagging me to write something about the LotusScript JSON classes that I created, so here goes. You can read some background information about the classes here.

First a little history. I originally wrote the JSONReader to support a particular piece of functionality we were putting into one of the templates for Quickr. In that case, an agent was to read JSON and output an Excel spreadsheet. Later, I wrote the JSONWriter class with methods to create JSON text on the fly (with methods such as BeginObject, BeginArray, Key, AppendValue, etc). This still was not completely satisfying. Finally, I added the ToJSON method to the JSONWriter class. This method accepts pretty much any data note (NotesDocument, NotesDocumentCollection, NotesView, NotesViewEntry, NotesViewEntryCollection) and outputs it as a JSON string. The data format is outlined on the download page. One potential use of this is in an agent that is called from a browser. The agent could respond with JSON and the browser could then parse it and process it as needed. If you want a different data format, you can change the private functions DocumentToJSON or EntryToJSON.

I want to share a real world example with you, but first I want to discuss the JSONWriter class a little more. It has several properties that can affect how data is output. If you pass a NotesDocument to JSONWriter, the output will include many properties of the NotesDocument and also all field data including a text representation of rich text. If you don’t want all fields, just pass an array of the fields you do want to the SetFieldsToOutput method. Maybe you only want a digest of the rich text items. In that case you can set the number of characters to output using the TruncateRichText property. There are others as well.

Now on with the show (and some code)! I was working on a QuickPlace (yes, QuickPlace) application where there was a need for a grid of reviewer data with an unknown number of rows (reviewers). I decided to make the data repository a JSON string which was stored in fields on the document. The form took care of parsing the JSON and presenting it for the browser. Without going into too much detail, an agent needed to update the JSON string when a reviewer approved a piece of the form. Enter stage right, JSONReader, JSONWriter, JSONArray, JSONObject.

Here is a simplified example of how the JSON string was defined:

{
“id_0″: {
name: “Project/Task Manager”,
reviewer: “John Doe”,
reviewerDN: “CN=John Doe/O=Acme”,
email: “jdoe@acme.com”,
status: STATUS_DEFAULT,
signature: “”,
completed: “”,
unid: “”
},
“id_1″: {
name: “Quality Assurance”,
reviewer: “Richard Roe”,
reviewerDN: “CN=Richard Roe/O=Acme”,
email: “rroe@acme.com”,
status: STATUS_DEFAULT,
signature: “”,
completed: “”,
unid: “”
}
}

The agent needed to set the status, signature, completed (a date), and the unid of the review document based on the id of the “row”. Here is the relevant code from the agent (p_vParms is a List with input arguments passed to the agent):

Dim jsonReader As JSONReader
Dim jsonObjAll As JSONObject
Dim jsonObjReview As JSONObject

sJSON = docTarget.GetItemValue(“c_ReviewerJSON”)(0)
Set jsonReader = New jsonReader

‘first put the entire JSON into an object
Set jsonObjAll = jsonReader.Parse(sJSON)

‘now get the specific object inside for the particular row we are updating (”Quality Assurance”)
Set jsonObjReview = jsonObjAll.GetItemValue(“id_1″)

‘update the fields in the object
Call jsonObjReview.ReplaceItemValue(“status”, p_vParms(ARG_STATUS))
Call jsonObjReview.ReplaceItemValue(“signature”, p_vParms(ARG_CN))
Call jsonObjReview.ReplaceItemValue(“completed”, Format(Now, “dd-mmm-yyyy”))
Call jsonObjReview.ReplaceItemValue(“unid”, p_vParms(ARG_UNID))

‘put our updated object back into the main object
Call jsonObjAll.ReplaceItemValue(p_vParms(“id_1″), jsonObjReview)

‘convert the object into a JSON string
sJSON = jsonObjAll.ToJSON

‘put the JSON back into the field
Call docTarget.ReplaceItemValue(“c_ReviewerJSON”, sJSON)

You may not realize it, but the JSONWriter class was used in this example. It was the engine behind the ToJSON call on the jsonObjAll object. I didn’t say it before, but the JSONArray and JSONObject classes also have the ToJSON method. This allows “round-tripping” of the JSON string. JSON string comes in, is parsed into LotusScript objects using JSONReader, those objects are modified using the JSONArray or JSONObject methods, and finally the resulting object is converted back to a JSON string using the ToJSON method.

Hopefully this gives you a taste of what can be accomplished using the JSON classes. Now back to your regular programming.

Share This

 Print This Post