There are two objects we use in all JSON interfaces. We use the TempBlob table and our custom JSON Interface Codeunit.
Abstract
JSON interface uses the same concept as a web service. The endpoint is defined by the Codeunit Name and the caller always supplies a form of request data (JSON) and expects a response data (JSON).
These interface calls therefore are only internal to the Business Central (NAV) server and are very fast. All the data is handled in memory only.
We define these interfaces by Endpoints. Some Endpoints have Methods. We call these Endpoints with a JSON. The JSON structure is predefined and every interface respects the same structure.
We have a single Codeunit that knows how to handle this JSON structure. Passing JSON to an interface requires a data container.
Interface Data
TempBlob is table 99008535. The table is simple but is has a lot of useful procedures.
table 99008535 TempBlob
{
Caption = 'TempBlob';
fields
{
field(1;"Primary Key";Integer)
{
Caption = 'Primary Key';
DataClassification = SystemMetadata;
}
field(2;Blob;BLOB)
{
Caption = 'Blob';
DataClassification = SystemMetadata;
}
}
keys
{
key(Key1;"Primary Key")
{
}
}
}
Wikipedia says: A Binary Large OBject (BLOB) is a collection of binary data stored as a single entity in a database management system. Blobs are typically images, audio or other multimedia objects, though sometimes binary executable code is stored as a blob. Database support for blobs is not universal.
We use this BLOB for our JSON data when we send a request to an interface and the interface response is also JSON in that same BLOB field.
For people that have been working with web requests we can say that TempBlob.Blob is used both for RequestStream and for ResponseStream.
TempBlob is only used as a form of Stream. We never use TempBlob to store data. We never do TempBlob.Get() or TempBlob.Insert(). And, even if the name indicates that this is a temporary record, we don’t define the TempBlob Record variable as temporary. There is no need for that since we never do any database call for this record.
Interface Helper Codeunit
We use a single Codeunit in all our solutions to prepare both request and response JSON and also to read from the request on the other end.
We have created a Codeunit that includes all the required procedures for the interface communication.
We have three functions to handle the basics;
- procedure Initialize()
- procedure InitializeFromTempBlob(TempBlob: Record TempBlob)
- procedure GetAsTempBlob(var TempBlob: Record TempBlob)
A typical flow of executions is to start by initializing the JSON. Then we add data to that JSON. Before we execute the interface Codeunit we use GetAsTempBlob to write the JSON into TempBlob.Blob. Every Interface Codeunit expects a TempBlob record to be passed to the OnRun() trigger.
codeunit 10008650 "ADV SDS Interface Mgt"
{
TableNo = TempBlob;
trigger OnRun()
var
Method: Text;
begin
with JsonInterfaceMgt do begin
InitializeFromTempBlob(Rec);
...
Inside the Interface Codeunit we initialize the JSON from the passed TempBlob record. At this stage we have access to all the data that was added to the JSON on the request side.
And, since the interface Codeunit will return TempBlob as well, we must make sure to put the response JSON in there before the execution ends.
with JsonInterfaceMgt do begin
Initialize();
AddVariable('Success', true);
GetAsTempBlob(Rec);
end;
JSON structure
The JSON is an array that contains one or more objects. An JSON array is represented with square brackets.
[]
The first object in the JSON array is the variable storage. This is an example of a JSON that passes two variables to the interface Codeunit.
[
{
"TestVariable": "TestVariableValue",
"TestVariable2": "TestVariableValue2"
}
]
All variables are stored in the XML format, using FORMAT(<variable>,0,9) and evaluated back using EVALUATE(<variable>,<json text value>,9). The JSON can then have multiple record related objects after the variable storage.
Adding data to the JSON
We have the following procedures for adding data to the JSON;
- procedure AddRecordID(Variant: Variant)
- procedure AddTempTable(TableName: Text; Variant: Variant)
- procedure AddFilteredTable(TableName: Text; FieldNameFilter: Text; Variant: Variant)
- procedure AddRecordFields(Variant: Variant)
- procedure AddVariable(VariableName: Text; Value: Variant)
- procedure AddEncryptedVariable(VariableName: Text; Value: Text)
I will write a more detailed blog about each of these methods and give examples of how we use them, but for now I will just do a short explanation of their usage.
If we need to pass a reference to a database table we pass the Record ID. Inside the interface Codeunit we can get the database record based on that record. Each Record ID that we add to the JSON is stored with the Table Name and we use either of these two procedures to retrieve the record.
- procedure GetRecord(var RecRef: RecordRef): Boolean
- procedure GetRecordByTableName(TableName: Text; var RecRef: RecordRef): Boolean
If we need to pass more than one record we can use pass all records inside the current filter and retrieve the result with
- procedure UpdateFilteredTable(TableName: Text; KeyFieldName: Text; var RecRef: RecordRef): Boolean
A fully populated temporary table with table view and table filters can be passed to the interface Codeunit by adding it to the JSON by name. When we use
- procedure GetTempTable(TableName: Text; var RecRef: RecordRef): Boolean
in the interface Codeunit to retrieve the temporary table we will get the whole table, not just the filtered content.
We sometimes need to give interface Codeunits access to the record that we are creating. Similar to the OnBeforeInsert() system event. If we add the record fields to the JSON we can use
- procedure GetRecordFields(var RecRef: RecordRef): Boolean
on the other end to retrieve the record and add or alter any field content before returning it back to the caller.
We have several procedures available to retrieve the variable values that we pass to the interface Codeunit.
- procedure GetVariableValue(var Value: Variant; VariableName: Text): Boolean
- procedure GetVariableTextValue(var TextValue: Text; VariableName: Text): Boolean
- procedure GetVariableBooleanValue(var BooleanValue: Boolean; VariableName: Text): Boolean
- procedure GetVariableDateValue(var DateValue: Date; VariableName: Text): Boolean
- procedure GetVariableDateTimeValue(var DateTimeValue: DateTime; VariableName: Text): Boolean
- procedure GetVariableDecimalValue(var DecimalValue: Decimal; VariableName: Text): Boolean
- procedure GetVariableIntegerValue(var IntegerValue: Integer; VariableName: Text): Boolean
- procedure GetVariableGUIDValue(var GuidValue: Guid; VariableName: Text): Boolean
- procedure GetVariableBLOBValue(var TempBlob: Record TempBlob; VariableName: Text): Boolean
- procedure GetVariableBLOBValueBase64String(var TempBlob: Record TempBlob; VariableName: Text): Boolean
- procedure GetEncryptedVariableTextValue(var TextValue: Text; VariableName: Text): Boolean
We use Base 64 methods in the JSON. By passing the BLOB to TempBlob.Blob we can use
TextValue := TempBlob.ToBase64String();
and then
TempBlob.FromBase64String(TextValue);
on the other end to pass a binary content, like images or PDFs.
Finally, we have the possibility to add and encrypt values that we place in the JSON. On the other end we can then decrypt the data to be used. This we use extensively when we pass sensitive data to and from our Azure Function.
Calling an interface Codeunit
As promised I will write more detailed blogs with examples. This is the current list of procedures we use to call interfaces;
- procedure ExecuteInterfaceCodeunitIfExists(CodeunitName: Text; var TempBlob: Record TempBlob; ErrorIfNotFound: Text)
- procedure TryExecuteInterfaceCodeunitIfExists(CodeunitName: Text; var TempBlob: Record TempBlob; ErrorIfNotFound: Text): Boolean
- procedure TryExecuteCodeunitIfExists(CodeunitName: Text; ErrorIfNotFound: Text) Success: Boolean
- procedure ExecuteAzureFunction() Success: Boolean
The first two expect a JSON to be passed using TempBlob. The third one we use to check for a simple true/false. We have no request data but we read the ‘Success’ variable from the response JSON.
For some of our functionality we use an Azure Function. We have created our function to read the same JSON structure we use internally. We also expect our Azure Function to respond with the sames JSON structure. By doing it that way, we can use the same functions to prepare the request and to read from the response as we do for our internal interfaces.
