NotesJsonNavigator, NotesJsonElement, NotesJsonArray, NotesJsonObject example

NotesJsonNavigator, NotesJsonElement, NotesJsonArray, NotesJsonObject are new classes in Domino Designer as of Notes V10.0.1. They are not yet documented in the Domino Designer Help, but you can find online documentation following the above links.

The documentation also contains some basic samples.

In this article, I will demonstrate how to use the classes beyond the basic examples.
I’ll also show, how you can use the new NotesHttpRequest class to connect to a server and read and parse view data as JSON.

The first thing you need to know is that the NotesJsonNavigator class does not like CRLF.
When you try to create a new NotesJsonNavigator from the following JSON data

Const colors = |{
  "colors": [
    {
      "color": "black",
      "category": "hue",
      "type": "primary",
      "code": {
        "rgba": [255,255,255,1],
        "hex": "#000"
      }
    },
    {
      "color": "white",
      "category": "value",
      "code": {
        "rgba": [0,0,0,1],
        "hex": "#FFF"
      }
    },
    {
      "color": "red",
      "category": "hue",
      "type": "primary",
      "code": {
        "rgba": [255,0,0,1],
        "hex": "#FF0"
      }
    },
    {
      "color": "blue",
      "category": "hue",
      "type": "primary",
      "code": {
        "rgba": [0,0,255,1],
        "hex": "#00F"
      }
    },
    {
      "color": "yellow",
      "category": "hue",
      "type": "primary",
      "code": {
        "rgba": [255,255,0,1],
        "hex": "#FF0"
      }
    },
    {
      "color": "green",
      "category": "hue",
      "type": "secondary",
      "code": {
        "rgba": [0,255,0,1],
        "hex": "#0F0"
      }
    }
  ]
}|

you will get an error.

You can remove all CRLF from the data using this helper function.

Public Function removeCRLF(json As String) As String
	removeCRLF = Replace(Replace(json, Chr(13), ""),Chr(10),"")
End Function

Let us create the NotesJsonNavigator from NotesSession first.

Dim session As New NotesSession 
Dim jsnav As NotesJSONNavigator 
	
Dim json As String
json = removeCRLF(colors)
Set jsnav = session.CreateJSONNavigator(json)

Now we can count how many different colors we would find in our JSON object

Dim el As NOTESJSONELEMENT
Dim arr As NOTESJSONARRAY
	
Set el = jsnav.GetFirstElement()

Set arr = el.value
	
MsgBox "Elements count: " + CStr(arr.size)

And finally, we want to get the value for the second color in the JSON object.

Although there is a GetNthElement (index) method, this method seems to be buggy or not yet fully implemented. GetNthElement(index) will always return the first element from the JSON object.

So we will use GetFirstElement and GetNextElement to navigate thru the object.

'Set el = arr.Getnthelement(2)
Set el = arr.GetFirstElement()
Set el = arr.GetNextElement()

Dim obj As NOTESJSONOBJECT
Set obj = el.Value
Set el = obj.Getelementbyname("color")
	 
MsgBox "color: " + CStr(el.Value)

The next sample creates a NotesHttpRequest and gets JSON from a view in a Notes application. Then we retrieve the UNID and NoteId from the data returned using the new NotesJson… classes.

%REM
	Library 10010.http
	Created Jan 1, 2019 by Ulrich Krause/singultus
	Description: Comments for Library
%END REM
Option Public
Option Declare

Public Sub httpGet
	Dim Session As New NotesSession        
	Dim ret As String
	Dim URL As String

	Dim user As String
	Dim password As String
	
	Dim httpReq As NotesHTTPRequest
	Set httpReq = session.CreateHttpRequest()
	
	httpReq.Preferstrings = True
	
	user = "firstname.lastname@tld.de"
	password = "pAssw0rd"
	
	URL = "https://yourserver/names.nsf/($certifiers)?readviewentries&outputformat=JSON"

	Call httpReq.Setheaderfield("Authorization", "Basic " + EncodeBase64 (user + ":" + password))

	Dim json As string
	json = httpReq.Get(URL)

	Dim jsnav As NotesJSONNavigator 
	Set jsnav = session.CreateJSONNavigator(removeCRLF(json))

	Dim el As NOTESJSONELEMENT
	Dim arr As NOTESJSONARRAY
	Dim obj As NOTESJSONOBJECT

	Set el = jsnav.GetElementByName("viewentry")

	Set arr = el.value
	Set el = arr.GetFirstElement()
	Set el = arr.GetNextElement()
	Set obj = el.Value
	Set el = obj.Getelementbyname("@unid")

	MsgBox "unid: " + CStr(el.Value)
	Set el = obj.Getelementbyname("@noteid")

	MsgBox "noteid: " + CStr(el.Value)

End Sub

Private Function removeCRLF(json As String) As String
	removeCRLF = Replace(Replace(json, Chr(13), ""),Chr(10),"")
End Function

Private Function EncodeBase64 (StrIn As String) As String
	Dim session As New NotesSession
	Dim stream As NotesStream
	Dim db As NotesDatabase
	Dim doc As NotesDocument
	Dim body As NotesMIMEEntity
	
	Set stream = session.CreateStream
	Call stream.WriteText (StrIn)
	
	Set db = session.CurrentDatabase
	Set doc = db.CreateDocument
	Set body  = doc.CreateMIMEEntity
	
	Call body.SetContentFromText (stream, "", ENC_NONE)
	Call body.EncodeContent (ENC_BASE64)
	
	EncodeBase64 = body.ContentAsText
	
	Call stream.Close
	Set doc = Nothing
End Function

6 thoughts on “NotesJsonNavigator, NotesJsonElement, NotesJsonArray, NotesJsonObject example

  1. Ulrich thank you for all of ou many post for the past few days and beyond. One thing missing for the LotusScript JSON class is the ability to setElements and Arrays. I have talked to HCL about this. Having the ability to “get” is OK but you need to also “set”.

  2. Hi Ulrich, thanks for the demo. I did some tests myself using json retrieved from web api (like google). It’s not only CRLF giving issues, other characters return exceptions too. According to HCL, there might be a defect in the character encoding of the json parser.
    A workaround is saving the json to a file and then read it back in a stream to parse it. That way, you won’t have to replace any characters. See also: https://stackoverflow.com/q/54167758

  3. NotesJSONNavigator is definitely a lot, lot faster than the ls.snapps classes.

    However, in tests I’m seeing a 64k input string character limit on CreateJSONNavigator, which kind of defeats the purpose of the classes being quicker.

    Can anyone confirm this?

      • Thank you!

        My original code used a >64kB NotesStream like this:
        stream.Position = 0
        Set jsnav = session.CreateJSONNavigator(stream.ReadText)

        But the error kept occurring until I made the NotesStream shorter.

        I also tried passing the NotesStream directly:
        Set jsnav = session.CreateJSONNavigator(stream)

        But this caused Designer to crash. So it looks like strings are the only option and they’re limited to 64kB 🙁

        Look forward to hearing HCL’s reply.

Leave a Reply

Your email address will not be published. Required fields are marked *

14 − nine =

This site uses Akismet to reduce spam. Learn how your comment data is processed.