Provides a range of instructions for interacting with JSON data stored in a local string.
KnowledgeKube includes functions for generating JSON data strings: JSONDataSource creates JSON using the results of a model data source query, while ServiceRequestJSON creates JSON using the results of a RESTful API service request.
Once you have a suitable JSON string, it must be Initialised by the function. This creates a data Object with a unique keyword. The object can then be manipulated by the function, for example by fetching specific values, adding or deleting data, or generating a filtered sub-set of the data. The object remains in memory until the session ends, or until the function is used to Close the object, removing it.
Syntax
ParseJSON( InstructionType, [Other parameters determined by InstructionType] );
Parameters
| Parameter Name | Type | Description | Optional? | Default Value |
|---|---|---|---|---|
| InstructionType | Integer OR String | Determines which instruction type is used by the function call. | No | n/a |
Output
The result of this function depends on the instruction type used. Refer to the following table for more information:
| Integer | String Equivalent | Instruction | Further Reading |
|---|---|---|---|
| 1 | Initialise | Creates a data object based on a local JSON string, assigning it a unique keyword. | ParseJSON (Initialise). |
| 2 | GetValue | Returns a string containing one or more values from an initialised JSON object. | ParseJSON (GetValue). |
| 3 | Close | Removes all initialised JSON objects from the current session. | ParseJSON (Close). |
| 4 | - | Updates the value of an item in an initialised JSON object, then returns the resulting string. | ParseJSON (Update). |
| 5 | - | Adds a new item to an initialised JSON object, then returns the resulting string. | ParseJSON (Add). |
| 6 | - | Removes an item from an initialised JSON object, then returns the resulting string. | ParseJSON (Remove). |
| 7 | Filter | Returns a string containing a filtered sub-set of data from an initialised JSON object. | ParseJSON (Filter). |
If you intend to make more than one change to the initialised data before closing it, you should assign the result of each change back to the original variable. This will automatically update the object data, allowing subsequent changes to have a cumulative effect. If you only intend to make a single change while the data is initialised, you can save the results of that change to whatever variable you prefer.
Use Case
After an application retrieves a set of data from an API service, the ParseJSON function could be used to query and manipulate the data. In this example, the following data is retrieved and assigned to the VARSunriseJSON variable:
{"results":{"sunrise":"5:12:33 AM","sunset":"7:35:16 PM","solar_noon":"12:23:55 PM","day_length":"14:22:43","civil_twilight_begin":"4:42:58 AM","civil_twilight_end":"8:04:51 PM","nautical_twilight_begin":"4:06:26 AM","nautical_twilight_end":"8:41:23 PM","astronomical_twilight_begin":"3:26:19 AM","astronomical_twilight_end":"9:21:30 PM"},"status":"OK"}
Before the variable's data can be manipulated, it must be initialised as an object using an expression like this:
ParseJSON( "Initialise", "OBJSunriseJSON", VARSunriseJSON );
The new object, named OBJSunriseJSON, can be interrogated using other ParseJSON instructions. The following example will extract the value of the item named sunset in results, assigning it to a variable called VARSunset:
VARSunset:= ParseJSON( "GetValue", "OBJSunriseJSON", 1, "results.sunset" );
In this example, the string extracted is as follows:
7:35:16 PM
To fetch all values from results instead of just one, the expression can be modified as follows:
VARResultsCSV:= ParseJSON( "GetValue", "OBJSunriseJSON", 2, "results" );
The CSV resulting from this expression is:
5:12:33 AM,7:35:16 PM,12:23:55 PM,14:22:43,4:42:58 AM,8:04:51 PM,4:06:26 AM,8:41:23 PM,3:26:19 AM,9:21:30 PM|
The following expression is then used to add a new item called wakeup to results, assigning the result back to VARSunriseJSON:
VARSunriseJSON:= ParseJSON( 5, "OBJSunriseJSON", "String", "results", "wakeup", "6:15:00 AM" );
After adding this item, the final value of VARSunriseJSON is as follows:
{"results":{"sunrise":"5:12:33 AM","sunset":"7:35:16 PM","solar_noon":"12:23:55 PM","day_length":"14:22:43","civil_twilight_begin":"4:42:58 AM","civil_twilight_end":"8:04:51 PM","nautical_twilight_begin":"4:06:26 AM","nautical_twilight_end":"8:41:23 PM","astronomical_twilight_begin":"3:26:19 AM","astronomical_twilight_end":"9:21:30 PM","wakeup":"6:15:00 AM"},"status":"OK"}
When the object is no longer required, the function should be used to close it:
ParseJSON( "Close" );