Transitional JSON Interface for Scripting

As part of the change from Flow to Statelake, we have updated the JSON libraries in use. This has many benefits in speed and functionality, but it has changed the objects and interfaces when using JSON in scripting.

This means that when converting scripts from Flow to Statelake there are two approaches you can use:

1. Rewrite your scripts using the new interfaces.
2. Use the transitional interfaces so that existing scripts can run with minimal logic changes.

It is strongly recommended that you do not use the transitional scripting interfaces for any new JSON scripting.

When to rewrite your scripts	When to use the transitional interfaces
You have a small number of scripts to migrate	You have a large number of scripts to migrate
You want to take advantage of improved and simpler interfaces that will continue to be improved and extended in the future.	You need to migrate to Statelake in a very short amount of time or with minimal code review

The new scripting interfaces are documented elsewhere, but below is a guide to the transitional interfaces.

Guide to converting legacy scripts to Transitional JSON Classes

The transitional classes create wrappers around the new JSON object model in Statelake to allow the new classes to behave like the old ones. Transitional classes include Flw in their name.

WARNING

When converting a script you should convert to EITHER transitional classes or the new Statelake JSON classes (which have the same names as the legacy Flow classes).

Do not mix the two class models in your scripts.

Flow JSON Class	Statelake Transitional JSON Class	Notes
TJSONValue	TFlwJSONValue
TJSONText		No direct equivalent, replace with TFlwJSONValue
TJSONObject	TFlwJSONObject
TJSONArray	TFlwJSONArray

Transitional JSON Classes

Class Function: TryCreateFlwJSON

Name	Parameters	Data Type	Notes
TryCreateFlwJSON	aString: String	TFlwJSONValue	Parses aString and returns a TFlwJSONValue which could by of any type or will be nil if parsing failed.

Class: TFlwJSONValue

Properties
Name	Data Type	Notes
AsArray	TFlwJSONArray
AsObject	TFlwJSONObject
AsText	TFlwJSONValue
ValueType	Returns the enumerated type of the value	One of: - jsString - jsNumber - jsBoolean - jsArray - jsObject - jsNull
AsBoolean	Boolean
AsDateTime	TDateTime
AsDouble	Double
AsGUID	TGUID
AsInt64	Int64
AsString	String
IsNull	Boolean
Name	String	Returns the name of the object
AsDisplayText	String	Returns formatted JSON

Methods
Name	Parameters	Data Type	Notes
CreateFromStream	aStream: TStream	TFlwJSONValue
CreateFromString	aString: String	TFlwJSONValue
LoadFromFile	aFileName: String
LoadFromStream	aStream: TStream
SaveToFile	aFileName: String aCompact: Boolean		If aCompact is false then output is formatted with whitespace
SaveToStream	aStream: TStream aCompact: Boolean		If aCompact is false then output is formatted with whitespace
Free			Frees the object and all of it’s children. Must be called on the root JSON object to avoid memory leaks.

Class: TFlwJSONObject

Constructors
Name	Parameters	Data Type	Notes
Create		TFlwJSONObject	Creates an empty object
CreateFromString	aString: String	TFlwJSONObject	Creates an object with contents parsed from aString

Properties
Name	Data Type	Notes
ValueCount	Integer
Values	TFlwJSONValue	Allows access by child name eg: obj['child_name']
ValueByIndex	TFlwJSONValue	Allows access by child index from zero eg: obj[3]
AsString	String
IsNull	Boolean
Name	String	Returns the name of the object
AsDisplayText	String	Returns formatted JSON

Methods
Name	Parameters	Data Type	Notes
AddBoolean	aName: String aValue: Boolean
AddDateTime	aName: String aValue: TDateTime
AddDouble	aName: String aValue: Double
AddGUID	aName: String aValue: TGUID
AddInteger	aName: String aValue: Integer
AddNull	aName: String
AddString	aName: String aValue: String
AddArray	aName: String	TFlwJSONArray
AddObject	aName: String	TFlwJSONObject
Contains	aValueName: String	Boolean
Delete	aName: String
DeleteByIndex	aIndex: Integer
FindValue	aName:String	TFlwJSONValue
LoadFromStream	aStream: TStream
OptBoolean	aName:String aDefault: Boolean	Boolean	Returns the value identified by aName. If it is not found, returns aDefault.
OptDateTime	aName:String aDefault: TDateTime	TDateTime	Returns the value identified by aName. If it is not found, returns aDefault.
OptDouble	aName:String aDefault: Double	Double	Returns the value identified by aName. If it is not found, returns aDefault.
OptInteger	aName:String aDefault: Integer	Integer	Returns the value identified by aName. If it is not found, returns aDefault.
OptString	aName:String aDefault: String	String	Returns the value identified by aName. If it is not found, returns aDefault.
Free			Frees the object and all of it’s children. Must be called on the root JSON object to avoid memory leaks.

Class: TFlwJSONArray

Constructors
Name	Parameters	Data Type	Notes
Create		TFlwJSONArray	Creates an empty object

Properties
Name	Data Type	Notes
Count	Integer
Items	TFlwJSONValue	Allows access by child index from zero eg: arr[3]
AsString	String
IsNull	Boolean
Name	String	Returns the name of the object
AsDisplayText	String	Returns formatted JSON

Methods
Name	Parameters	Data Type	Notes
AddBoolean	aValue: Boolean
AddDateTime	aValue: TDateTime
AddDouble	aValue: Double
AddGUID	aValue: TGUID
AddInteger	aValue: Integer
AddNull
AddString	aValue: String
AddArray		TFlwJSONArray
AddObject		TFlwJSONObject
Delete	aIndex: Integer
Free			Frees the object and all of it’s children. Must be called on the root JSON object to avoid memory leaks.