Technote: Limitations of NotesHTTPRequest and NotesJSONNavigator with future considerations

If you are already using the NotesHTTPRequest and / or NotesJSONNavigator classes in your code and you are experiencing one of the following issues, here is an important technote for you.

  • SPR# DCONB8VMAV – NotesJSONNavigator is unable to parse JSON content > 64k
  • SPR# ASHEB95LFR – Unable to parse JSON string: Missing a name for object member, offset 1
  • SPR# DCONB8F6JV – bad character conversion happening in NotesHTTPRequest response
  • SPR# ASHEB95LFR – NotesJSONNavigator unable to navigate a string which contains new lines and carriage returns
  • SPR# DCONBB2KNR – NotesJSONNavigator experiencing severe issues when parsing packages with empty string values
  • SPR# JCORBB2KWU – Unable to Post > 64K String in NotesHTTPRequest
  • SPR# DCONBB44T4 – Creating a NotesJSONNavigator from nulled response causes crash

https://www-01.ibm.com/support/docview.wss?uid=ibm10875724


NotesHttpRequest LotusScript example

NotesHttpRequest is a new LotusScript class in Notes V10.0.1 used to make HTTP requests to web servers.

The example wraps the get(), post(), put() and deleteResource() methods in a LotusScript class.

I have also put together a small Node.js / Express.js project that can be used as test server for the NotesHttpRequest example.

Class HttpRequestWrapper

%REM
	Library 10010.http
	Created Jan 8, 2019 by Ulrich Krause/singultus
%END REM
Option Public
Option Declare

Const BASE_URL_PORT = "http://192.168.178.35:3001/api/"
Const CLASS_CUSTOMER ="customers"

Const CUSTOMER_5 = |{
					"firstname" : "Ulrich",
					"lastname" : "Krause",
					"age" : 59,
					"id" : 5
				}|

Const CUSTOMER_5_UPDATE = |{
					"firstname" : "Heinz Ulrich",
					"lastname" : "Krause",
					"age" : 59,
					"id" : 5
				}|
				
%REM
	Class HttpRequestWrapper
%END REM
Public Class HttpRequestWrapper
	
	Private m_session As NotesSession
	Private m_url As String
	Private m_class As String
	Private m_json As String
	Private m_httpRequest As NOTESHTTPREQUEST
	
	%REM
		Sub New
	%END REM
	Public Sub New()
		Set m_session = New NotesSession
		Set m_httpRequest = me.m_session.CreateHttpRequest()
		
		m_httpRequest.Preferstrings = True
		
		m_url = BASE_URL_PORT
		m_class = CLASS_CUSTOMER
	End Sub
	
	%REM
		Function getApiVersion
	%END REM
	Public sub getApiVersion()
		m_json = m_httpRequest.Get(BASE_URL_PORT)
		MsgBox m_json
	End Sub
	
	%REM
		Sub getAllObj
	%END REM
	Public Sub getAllObj()
		m_json = m_httpRequest.Get(_
		BASE_URL_PORT + CLASS_CUSTOMER)
		
		MsgBox m_json
	End Sub
	
	%REM
		Sub getObjById
	%END REM
	Public Sub getObjById(id As String)
		m_json = m_httpRequest.Get(_
		BASE_URL_PORT + CLASS_CUSTOMER + "/" + id)
		
		MsgBox m_json	
	End Sub
	
	%REM
		Sub createObj
	%END REM
	Public Sub createObj()
		m_json = m_httpRequest.Post(_
		BASE_URL_PORT + CLASS_CUSTOMER,_
		removeCRLF(CUSTOMER_5))
		
		MsgBox m_json	
	End Sub
	
	%REM
		Sub updateObj
	%END REM
	Public Sub updateObj(id As String)
		m_json = m_httpRequest.Put(_
		BASE_URL_PORT + CLASS_CUSTOMER + "/" + id,_
		removeCRLF(CUSTOMER_5_UPDATE))
		
		MsgBox m_json
	End Sub
	
	%REM
		Sub deleteObj
	%END REM
	Public Sub deleteObj(id As String)
		m_json = m_httpRequest.DeleteResource(_
		BASE_URL_PORT + CLASS_CUSTOMER + "/" + id)
		
		MsgBox m_json
	End Sub
End Class

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

Sample usage:

Use "10010.http"

Sub Click(Source As Button)
	Dim httpRequestWrapper As New HttpRequestWrapper()

	Call httpRequestWrapper.getApiVersion()
	Call httpRequestWrapper.createObj()
	Call httpRequestWrapper.deleteObj("3")
	Call httpRequestWrapper.getAllObj()
	Call httpRequestWrapper.updateObj("5")
	Call httpRequestWrapper.getObjById("5")
End Sub



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