We have several ways of using the JSON interfaces. I will give few examples with the required C/AL code. I will be using Advania’s Online Banking solution interfaces for examples.
The Advania’s Online Banking solution is split into several different modules. The main module has the general framework. Then we have communication modules and functionality modules.
On/Off Question
A communication module should not work if the general framework does not exist or is not enabled for the current company. Hence, I need to ask the On/Off question
This is triggered by calling the solution enabled Codeunit.
IF NOT JsonInterfaceMgt.TryExecuteCodeunitIfExists('ADV Bank Services Enabled Mgt.','') THEN BEGIN
SetupNotification.MESSAGE := NotificationMsg;
SetupNotification.SEND;
END;The interface function will search for the Codeunit, check for execution permissions and call the Codeunit with an empty request BLOB.
The “Enabled” Codeunit must respond with a “Success” variable of true or false.
[External] TryExecuteCodeunitIfExists(CodeunitName : Text;ErrorIfNotFound : Text) Success : Boolean
Object.SETRANGE(Type,Object.Type::Codeunit);
Object.SETRANGE(Name,CodeunitName);
IF NOT Object.FINDFIRST THEN
IF ErrorIfNotFound <> '' THEN
ERROR(ErrorIfNotFound)
ELSE
EXIT;
IF NOT HasCodeunitExecuteLicense(Object.ID,ErrorIfNotFound) THEN EXIT;
CODEUNIT.RUN(Object.ID,TempBlob);
InitializeFromTempBlob(TempBlob);
GetVariableBooleanValue(Success,'Success');The “Enabled” Codeunit will test for Setup table read permission and if the “Enabled” flag has been set in the default record.
OnRun(VAR Rec : Record TempBlob)
TestEnabled(Rec);
LOCAL TestEnabled(VAR TempBlob : Record TempBlob)
WITH JsonInterfaceMgt DO BEGIN
Initialize;
AddVariable('Success',IsServiceEnabled);
GetAsTempBlob(TempBlob);
END;
IsServiceEnabled() : Boolean
IF NOT Setup.READPERMISSION THEN EXIT;
EXIT(Setup.GET AND Setup.Enabled);This is how we can make sure that a module is installed and enabled before we start using it or any of the dependent modules.
Table Access Interface
The main module has a standard response table. We map some of the communication responses to this table via Data Exchange Definition. From other modules we like to be able to read the response from the response table.
The response table uses a GUID value for a primary key and has an integer field for the “Data Exchange Entry No.”. From the sub module we ask if a response exists for the current “Data Exchange Entry No.” by calling the interface.
FindResponse(DataExchEntryNo : Integer) Success : Boolean
WITH JsonInterfaceMgt DO BEGIN
Initialize;
AddVariable('DataExchEntryNo',DataExchEntryNo);
GetAsTempBlob(TempBlob);
ExecuteInterfaceCodeunitIfExists('ADV Bank Serv. Resp. Interface',TempBlob,ResponseInterfaceErr);
InitializeFromTempBlob(TempBlob);
GetVariableBooleanValue(Success,'Success');
END;The Interface Codeunit for the response table will filter on the “Data Exchange Entry No.” and return the RecordID for that record if found.
OnRun(VAR Rec : Record TempBlob)
WITH JsonInterfaceMgt DO BEGIN
InitializeFromTempBlob(Rec);
GetVariableIntegerValue(DataExchEntryNo,'DataExchEntryNo');
Response.SETRANGE("Data Exch. Entry No.",DataExchEntryNo);
AddVariable('Success',Response.FINDFIRST);
IF Response.FINDFIRST THEN
AddRecordID(Response);
GetAsTempBlob(Rec);
END;If the response is found we can ask for the value of any field from that record by calling
GetFieldValue(FieldName : Text) FieldValue : Text
WITH JsonInterfaceMgt DO
IF GetRecordByTableName('ADV Bank Service Response',RecRef) THEN
IF DataTypeMgt.FindFieldByName(RecRef,FldRef,FieldName) THEN
IF FORMAT(FldRef.TYPE) = 'BLOB' THEN BEGIN
TempBlob.Blob := FldRef.VALUE;
FieldValue := TempBlob.ReadAsTextWithCRLFLineSeparator();
END ELSE
FieldValue := FORMAT(FldRef.VALUE,0,9);Processing Interface
Some processes can be both automatically and manually executed. For manual execution we like to display a request page on a Report. On that request page we can ask for variables, settings and verify before executing the process.
For automatic processing we have default settings and logic to find the correct variables before starting the process. And since one module should be able to start a process in the other then we use the JSON interface pattern for the processing Codeunit.
We also like to include the “Method” variable to add flexibility to the interface. Even if there is only one method in the current implementation.
OnRun(VAR Rec : Record TempBlob)
WITH JsonInterfaceMgt DO BEGIN
InitializeFromTempBlob(Rec);
IF NOT GetVariableTextValue(Method,'Method') OR (Method = '') THEN
ERROR(MethodNotFoundErr);
CASE Method OF
'BankAccountProcessing':
BankAccountProcessing(JsonInterfaceMgt);
END;
END;
LOCAL BankAccountProcessing(JsonInterfaceMgt : Codeunit "IS Json Interface Mgt.")
CheckSetup;
CompanyInformation.GET;
WITH JsonInterfaceMgt DO BEGIN
GetVariableTextValue(ClaimExportImportFormatCode, 'ClaimExportImportFormatCode');
GetVariableTextValue(BankAccountNo, 'BankAccountNo');
GetVariableDateValue(StartDate,'StartDate');
GetVariableDateValue(EndDate,'EndDate');
ValidateStartDate;
ValidateEndDate;
ValidateImportFormat;
BankAccount.SETRANGE("No.", BankAccountNo);
ClaimExportImportFormat.GET(ClaimExportImportFormatCode);
Initialize;
AddVariable('BankAccNo',BankAccountNo);
AddVariable('ClaimantID',CompanyInformation."Registration No.");
AddVariable('StartDate',StartDate);
AddVariable('EndDate',EndDate);
GetAsTempBlob(TempBlob);
Window.OPEN(ImportingFromBank);
IF BankAccount.FINDSET THEN REPEAT
DataExchDef.GET(ClaimExportImportFormat."Resp. Data Exch. Def. Code");
DataExch.INIT;
DataExch."Related Record" := BankAccount.RECORDID;
DataExch."Table Filters" := TempBlob.Blob;
DataExch."Data Exch. Def Code" := DataExchDef.Code;
DataExchLineDef.SETRANGE("Data Exch. Def Code",DataExchDef.Code);
DataExchLineDef.FINDFIRST;
DataExch."Data Exch. Line Def Code" := DataExchLineDef.Code;
DataExchDef.TESTFIELD("Ext. Data Handling Codeunit");
CODEUNIT.RUN(DataExchDef."Ext. Data Handling Codeunit",DataExch);
DataExch.INSERT;
IF DataExch.ImportToDataExch(DataExchDef) THEN BEGIN
DataExchMapping.GET(DataExchDef.Code,DataExchLineDef.Code,DATABASE::"ADV Claim Payment Batch Entry");
IF DataExchMapping."Pre-Mapping Codeunit" <> 0 THEN
CODEUNIT.RUN(DataExchMapping."Pre-Mapping Codeunit",DataExch);
DataExchMapping.TESTFIELD("Mapping Codeunit");
CODEUNIT.RUN(DataExchMapping."Mapping Codeunit",DataExch);
IF DataExchMapping."Post-Mapping Codeunit" <> 0 THEN
CODEUNIT.RUN(DataExchMapping."Post-Mapping Codeunit",DataExch);
END;
DataExch.DELETE(TRUE);
UNTIL BankAccount.NEXT = 0;
Window.CLOSE;
END;Reading through the code above we can see that we are also using the JSON interface to pass settings to the Data Exchange Framework. We put the JSON configuration into the “Table Filters” BLOB field in the Data Exchange where we can use it later in the data processing.
From the Report we start the process using the JSON interface.
Bank Account - OnPreDataItem()
WITH JsonInterfaceMgt DO BEGIN
Initialize;
AddVariable('Method','BankAccountProcessing');
AddVariable('ClaimExportImportFormatCode', ClaimExportImportFormat.Code);
AddVariable('BankAccountNo', BankAccount."No.");
AddVariable('StartDate',StartDate);
AddVariable('EndDate',EndDate);
GetAsTempBlob(TempBlob);
ExecuteInterfaceCodeunitIfExists('ADV Import BCP Interface', TempBlob, '');
END;The ExecuteInterfaceCodeunitIfExists will also verify that the Interface Codeunit exists and also verify the permissions before executing.
[External] ExecuteInterfaceCodeunitIfExists(CodeunitName : Text;VAR TempBlob : Record TempBlob;ErrorIfNotFound : Text)
Object.SETRANGE(Type,Object.Type::Codeunit);
Object.SETRANGE(Name,CodeunitName);
IF NOT Object.FINDFIRST THEN
IF ErrorIfNotFound <> '' THEN
ERROR(ErrorIfNotFound)
ELSE
EXIT;
IF NOT HasCodeunitExecuteLicense(Object.ID,ErrorIfNotFound) THEN EXIT;
CODEUNIT.RUN(Object.ID,TempBlob)Extensible Interface
For some tasks it might be simple to have a single endpoint (Interface Codeunit) for multiple functionality. This can be achieved by combining Events and Interfaces.
We start by reading the required parameters from the JSON and then we raise an event for anyone to respond to the request.
OnRun(VAR Rec : Record TempBlob)
WITH JsonInterfaceMgt DO BEGIN
InitializeFromTempBlob(Rec);
IF NOT GetVariableTextValue(InterfaceType,'InterfaceType') THEN
ERROR(TypeErr);
IF NOT GetVariableTextValue(Method,'Method') THEN
ERROR(MethodErr);
OnInterfaceAccess(InterfaceType,Method,Rec);
END;
LOCAL [IntegrationEvent] OnInterfaceAccess(InterfaceType : Text;Method : Text;VAR TempBlob : Record TempBlob)We can also pass the JSON Interface Codeunit, as that will contain the full JSON and will contain the full JSON for the response.
OnRun(VAR Rec : Record TempBlob)
WITH JsonInterfaceMgt DO BEGIN
InitializeFromTempBlob(Rec);
IF NOT GetVariableTextValue(InterfaceType,'InterfaceType') THEN
ERROR(TypeErr);
IF NOT GetVariableTextValue(Method,'Method') THEN
ERROR(MethodErr);
OnInterfaceAccess(InterfaceType,Method,JsonInterfaceMgt);
GetAsTempBlob(Rec);
END;
LOCAL [IntegrationEvent] OnInterfaceAccess(InterfaceType : Text;Method : Text;VAR JsonInterfaceMgt : Codeunit "IS Json Interface Mgt.")One of the subscribers could look like this
LOCAL [EventSubscriber] OnInterfaceAccess(InterfaceType : Text;Method : Text;VAR JsonInterfaceMgt : Codeunit "IS Json Interface Mgt.")
IF InterfaceType = 'Claim' THEN
CASE Method OF
'Register':
Register(JsonInterfaceMgt);
'Edit':
Edit(JsonInterfaceMgt);
'AddExportImportFormat':
AddExportImportFormat(JsonInterfaceMgt);
'GetSetupCodeunitID':
GetSetupCodeunitID(JsonInterfaceMgt);
'GetDirection':
GetDirection(JsonInterfaceMgt);
'GetServiceUrl':
GetServiceUrl(JsonInterfaceMgt);
'GetExportImportFormat':
GetExportImportFormat(JsonInterfaceMgt);
'GetServiceMethod':
GetServiceMethod(JsonInterfaceMgt);
'ShowAndGetClaimFormat':
ShowAndGetClaimFormat(JsonInterfaceMgt);
'GetDataExchangeDefintionWithAction':
GetDataExchangeDefintionWithAction(JsonInterfaceMgt);
'GetOperationResultForClaimant':
GetOperationResultForClaimant(JsonInterfaceMgt);
'ShowClaimPayment':
ShowClaimPayment(JsonInterfaceMgt)
ELSE
ERROR(MethodErr,Method);
END;Registration Interface
This pattern is similar to the discovery pattern, where an Event is raised to register possible modules into a temporary table. Example of that is the “OnRegisterServiceConnection” event in Table 1400, Service Connection.
Since we can’t have Event Subscriber in one module listening to an Event Publisher in another, without having compile dependencies, we have come up with a different solution.
We register functionality from the functionality module and the list of modules in stored in a database table. The table uses a GUID and the Language ID for a primary key, and then the view is filtered by the Language ID to only show one entry for each module.
This pattern gives me a list of possible modules for that given functionality. I can open the Setup Page for that module and I can execute the Interface Codeunit for that module as well. Both the Setup Page ID and the Interface Codeunit ID are object names.
The registration interface uses the Method variable to select the functionality. It can either register a new module or it can execute the method in the modules.
OnRun(VAR Rec : Record TempBlob)
WITH JsonInterfaceMgt DO BEGIN
InitializeFromTempBlob(Rec);
IF NOT GetVariableTextValue(Method,'Method') THEN
ERROR(MethodErr);
CASE Method OF
'Register':
RegisterCollectionApp(JsonInterfaceMgt);
ELSE
ExecuteMethodInApps(Rec);
END;
END;
LOCAL RegisterCollectionApp(JsonInterfaceMgt : Codeunit "IS Json Interface Mgt.")
WITH BankCollectionModule DO BEGIN
JsonInterfaceMgt.GetVariableGUIDValue(ID,'ID');
"Language ID" := GLOBALLANGUAGE();
IF FIND THEN EXIT;
INIT;
JsonInterfaceMgt.GetVariableTextValue(Name,'Name');
JsonInterfaceMgt.GetVariableTextValue("Setup Page ID",'SetupPageID');
JsonInterfaceMgt.GetVariableTextValue("Interface Codeunit ID",'InterfaceCodeunitID');
INSERT;
END;
[External] ExecuteMethodInApps(VAR TempBlob : Record TempBlob)
WITH BankCollectionModule DO BEGIN
SETCURRENTKEY("Interface Codeunit ID");
IF FINDSET THEN REPEAT
JsonInterfaceMgt.ExecuteInterfaceCodeunitIfExists("Interface Codeunit ID",TempBlob,'');
SETFILTER("Interface Codeunit ID",'>%1',"Interface Codeunit ID");
UNTIL NEXT = 0;
END;In the “ExecuteMethodInApps” function I use the filters to make sure to only execute each Interface Codeunit once.
The registration is executed from the Setup & Configuration in the other module.
[External] RegisterCollectionApp()
WITH JsonInterfaceMgt DO BEGIN
Initialize();
AddVariable('Method','Register');
AddVariable('ID',GetCollectionAppID);
AddVariable('Name',ClaimAppName);
AddVariable('SetupPageID','ADV Claim Setup');
AddVariable('InterfaceCodeunitID','ADV Claim Interface Access');
GetAsTempBlob(TempBlob);
ExecuteInterfaceCodeunitIfExists('ADV Bank Collection App Access',TempBlob,'');
END;Extend functionality using the Registered Modules.
As we have been taught we should open our functionality for other modules. This is done by adding Integration Events to our code.
LOCAL [IntegrationEvent] OnBeforePaymentPost(ClaimPaymentEntry : Record "ADV Claim Payment Batch Entry";VAR CustLedgEntry : Record "Cust. Ledger Entry";VAR UseClaimPaymentApplication : Boolean;VAR ToAccountType : 'G/L Account,Customer,Vendor,Bank Acco
LOCAL [IntegrationEvent] OnBeforePostGenJnlLine(VAR ClaimPaymentEntry : Record "ADV Claim Payment Batch Entry";VAR GenJournalLine : Record "Gen. Journal Line";VAR AppliedDocType : Option;VAR AppliedDocNo : Code[20];VAR AppliesToID : Code[50])
Where the Subscriber that needs to respond to this Publisher is in another module we need to extend the functionality using JSON interfaces.
First, we create a Codeunit within the Publisher module with Subscribers. The parameters in the Subscribers are converted to JSON and passed to the possible subscriber modules using the “ExecuteMethodInApps” function above.
LOCAL [EventSubscriber] OnBeforeClaimPaymentInsert(VAR ClaimPaymentEntry : Record "ADV Claim Payment Batch Entry")
GetClaimSettings(ClaimPaymentEntry);
LOCAL GetClaimSettings(VAR ClaimPaymentEntry : Record "ADV Claim Payment Batch Entry") Success : Boolean
JsonInterfaceMgt.Initialize;
JsonInterfaceMgt.AddVariable('Method','GetClaimSettings');
JsonInterfaceMgt.AddVariable('ClaimantID',ClaimPaymentEntry."Claimant Registration No.");
JsonInterfaceMgt.AddVariable('ClaimKey',ClaimPaymentEntry."Claim Account No.");
JsonInterfaceMgt.AddVariable('InterestDate',ClaimPaymentEntry."Interest Date");
JsonInterfaceMgt.GetAsTempBlob(TempBlob);
BankCollectionAppAccess.ExecuteMethodInApps(TempBlob);
JsonInterfaceMgt.InitializeFromTempBlob(TempBlob);
IF NOT JsonInterfaceMgt.GetVariableBooleanValue(Success,'Success') THEN EXIT;
ClaimPaymentEntry."Batch Code" := GetJsonProperty('BatchCode');
ClaimPaymentEntry."Template Code" := GetJsonProperty('TemplateCode');
ClaimPaymentEntry."Source Code" := GetJsonProperty('SourceCode');
ClaimPaymentEntry."Customer No." := GetJsonProperty('CustomerNo');
ClaimPaymentEntry."Customer Name" := GetJsonProperty('CustomerName');The module that is extending this functionality will be able to answer to these request and supply the required response.
OnRun(VAR Rec : Record TempBlob)
IF NOT Setup.READPERMISSION THEN EXIT;
Setup.GET;
WITH JsonInterfaceMgt DO BEGIN
InitializeFromTempBlob(Rec);
IF NOT GetVariableTextValue(Method,'Method') THEN
ERROR(MethodErr);
CASE Method OF
'Register':
RegisterCollectionApp();
'GetByCustLedgEntryNo':
ReturnClaimForCustLedgEntryNo(Rec);
'GetCustLedgEntryLinkInfo':
ReturnClaimInfoForCustLedgEntryNo(Rec);
'DisplayCustLedgEntryLinkInfo':
DisplayClaimInfoForCustLedgEntryNo();
'GetClaimSettings':
ReturnClaimSettings(Rec);
'GetClaimTempateSettings':
ReturnClaimTemplateSettings(Rec);
'GetClaimPaymentApplicationID':
ReturnClaimPaymentApplicationID(Rec);
'AddToGenDataRequest':
ReturnGenDataRequest(Rec);
END;
END;Azure Function
The last example we will show is the Azure Function. Some functionality requires execution in an Azure Function.
By making sure that our Azure Function understands the same JSON format used in our JSON Interface Codeunit we can easily prepare the request and read the response using the same methods.
We have the Azure Function Execution in that same JSON Codeunit. Hence, easily prepare the request and call the function in a similar way as for other interfaces.
JsonInterfaceMgt.Initialize;
JsonInterfaceMgt.AddVariable('Method',ServiceMethod);
JsonInterfaceMgt.AddVariable('Url',ServiceUrl);
JsonInterfaceMgt.AddVariable('Username',Username);
JsonInterfaceMgt.AddEncryptedVariable('Password',Password);
JsonInterfaceMgt.AddVariable('Certificate',CertificateValueAsBase64);
JsonInterfaceMgt.AddVariable('Xml',TempBlob.ReadAsTextWithCRLFLineSeparator);
Success := JsonInterfaceMgt.ExecuteAzureFunction;
IF JsonInterfaceMgt.GetVariableBLOBValue(TempBlob,'Xml') THEN
LogMgt.SetIncoming(TempBlob.ReadAsTextWithCRLFLineSeparator,'xml')
ELSE
LogMgt.SetIncoming(JsonInterfaceMgt.GetJSON,'json');
IF Success THEN
DataExch."File Content" := TempBlob.Blob;The request JSON is posted to the Azure Function and the result read with a single function.
[External] ExecuteAzureFunction() Success : Boolean
GetAsTempBlob(TempBlob);
IF (NOT GetVariableTextValue(AzureServiceURL,'AzureServiceURL')) OR (AzureServiceURL = '') THEN
AzureServiceURL := 'https://<azurefunction>.azurewebsites.net/api/AzureProxy?code=<some access code>';
OnBeforeExecuteAzureFunction(TempBlob,AzureServiceURL,OmmitWebRequest);
IF NOT OmmitWebRequest THEN BEGIN
HttpWebRequestMgt.Initialize(AzureServiceURL);
HttpWebRequestMgt.DisableUI;
HttpWebRequestMgt.SetMethod('POST');
HttpWebRequestMgt.SetContentType('application/json');
HttpWebRequestMgt.SetReturnType('application/json');
HttpWebRequestMgt.AddBodyBlob(TempBlob);
TempBlob.INIT;
TempBlob.Blob.CREATEINSTREAM(ResponseInStream,TEXTENCODING::UTF8);
IF NOT HttpWebRequestMgt.GetResponse(ResponseInStream,HttpStatusCode,ResponseHeaders) THEN
IF NOT HttpWebRequestMgt.ProcessFaultResponse('http://www.advania.is') THEN BEGIN
Initialize;
AddVariable('Exception',GETLASTERRORTEXT);
EXIT(FALSE);
END;
END;
InitializeFromTempBlob(TempBlob);
GetVariableBooleanValue(Success,'Success');
We use the “OnBeforeExecuteAzureFunction” event with a manual binding for our Unit Tests.
In the Azure Function we read the request with standard JSON functions
dynamic data = await req.Content.ReadAsAsync<object>();
Newtonsoft.Json.Linq.JArray jRequestArray = Newtonsoft.Json.Linq.JArray.Parse(data.ToString());
string Method = jRequestArray.First().Value<string>("Method") ?? "Undefined";
Then based on the Method we call each functionality with the request and write the response to the response JSON.
Newtonsoft.Json.Linq.JArray jResponseArray = new Newtonsoft.Json.Linq.JArray();
Newtonsoft.Json.Linq.JObject jResponseObject = new Newtonsoft.Json.Linq.JObject();
try
{
switch (Method)
{
case "Ping":
success = true;
response = "Hello " + (jRequestArray.First().Value<string>("Name") ?? "Undefined") + "!";
break;
case "IOBS2005WSE2.GetAccountStatement":
xml = jRequestArray.First().Value<string>("Xml") ?? "";
success = IOBS2005WSE2.Helper.GetAccountStatement(
jRequestArray.First().Value<string>("Url") ?? "",
jRequestArray.First().Value<string>("Username") ?? "",
Decrypt(jRequestArray.First().Value<string>("Password") ?? ""),
jRequestArray.First().Value<string>("Certificate") ?? "",
ref xml);
jResponseObject.Add(new Newtonsoft.Json.Linq.JProperty("Xml", xml));
response = "";
break;
...
default:
response = "Method not found";
break;
}
jResponseObject.Add(new Newtonsoft.Json.Linq.JProperty("Response", response));
}
catch (System.Exception exception)
{
httpStatusCode = HttpStatusCode.BadRequest;
jResponseObject.Add(new Newtonsoft.Json.Linq.JProperty("Request", request));
jResponseObject.Add(new Newtonsoft.Json.Linq.JProperty("Message", exception.Message));
jResponseObject.Add(new Newtonsoft.Json.Linq.JProperty("StackTrace", exception.StackTrace.ToString()));
jResponseObject.Add(new Newtonsoft.Json.Linq.JProperty("InnerException", exception.InnerException.Message));
}
jResponseObject.Add(new Newtonsoft.Json.Linq.JProperty("Success", success));
jResponseArray.Add(jResponseObject);
return req.CreateResponse(httpStatusCode, jResponseArray); Conclusion
Having standard ways of talking between modules and solutions has opened up for a lot of flexibility. We like to keep our solutions as small as possible.
We could mix “Methods” and “Versions” if we at later time need to be able to extend some of the interfaces. We need to honor the contract we have made for the interfaces. We must not make breaking changes to the interfaces, but we sure can extend them without any problems.
By attaching the JSON Interface Codeunit to the post I hope that you will use this pattern in your solutions. Use the Code freely. It is supplies as-is and without any responsibility, obligations or requirements.
