Introduction

There are multiple ways of exposing web services in Microsoft Dynamics NAV that are used by external applications to:

Create, update or delete data into the ERP system (ex.: Create a Sales Order) or
Get data from the ERP system (ex.: get a list of Items).

Microsoft Dynamics NAV has the capability to support creation and publishing of Dynamics NAV functionality as web services: Pages can be exposed as SOAP and OData, Codeunits as SOAP and Queries as OData. A very simple example of how to use this functionality can be found here.

Why and how to use data in JSON format with NAV web services

These days most of the applications communicate with each other using JSON format because of it’s numerous benefits: it is easy to learn, read and understand, it’s fast etc.

So, what we want to have many times when we create integrations that create/update/delete or retrieve data from NAV is the possibility to have methods that accept as argument a JSON string, use the data from that string to do something inside NAV and then return another JSON string with the results of what happened into the system.

Example of working with JSON data in NAV

In order to demonstrate this pattern, we created a simple example based on the following scenario: we need to create Sales Orders (with Header and Lines) . The external application will send Sales Order related data in JSON format to Microsoft Dynamics NAV webservice function. Then Microsoft Dynamics NAV will parse the data and create Sales Header and Lines based on it. We also need to create and return a JSON Response: for each created Sales Order Header and Line, we provide inforomation that the entity was created with success and if an error occurred, we write that the entity was not created and the error message.

How the Request JSON looks like

{
	"SalesOrders": [
		{
			"OrderNo" : "Ext1",
			"CustomerNo": "10000",
			"OrderDate": "2010-11-30",
			"SalesOrderLines": [
				{
					"ItemNo": "1000",
					"LocationCode": "BLAUW",
					"Quantity": 1,
					"UnitPrice": 10
				},
				{
					"ItemNo": "2000",
					"LocationCode": "BLAUW",
					"Quantity": 2,
					"UnitPrice": 15
				}
			]
		},
		{
			"OrderNo" : "Ext2",
			"CustomerNo": "20000",
			"OrderDate": "2010-11-29",
			"SalesOrderLines": [
				{
					"ItemNo": "1960-S",
					"LocationCode": "GEEL",
					"Quantity": 1,
					"UnitPrice": 4000
				}
			]
		}
	]
}

Explanation: the Request JSON contains an Array of Sales Orders, so creation of multiple Sales Orders in 1 web service call is possible (batch creation). Each Sales Order element of the Sales Orders array contains data about the Sales Order Header and then an Array of one or more Sales Order Lines. For each Sales Order Header, the system will create one Sales Line for each element in the SalesOrderLines array.

How the Response JSON looks like

[
	{
		"OrderNo": "Ext1",
		"NAVOrderNo": "1018",
		"Result": "Created",
		"OrderLines": [
			{
				"LineNo": "10000",
				"Result": "Created"
			},
			{
				"LineNo": "20000",
				"Result": "Created"
			}
		]
	},
	{
		"OrderNo": "Ext2",
		"NAVOrderNo": "1019",
		"Result": "Created",
		"OrderLines": [
			{
				"LineNo": "10000",
				"Result": "Created"
			}
		]
	}
]

Explanation: for each Order Header and Line we create and return a log so the external application can use it in order to understand what happened inside NAV.

NAV object

We use Codeunit exposed as Web Service:

This codeunit has only 1 global method “GetJson” which has 2 arguments: the ‘Method’ name and the ‘Params’ JSON string. This method Returns a string.

Method argument: the name of method that we want to call. Ex: CreateSalesOrders
Params argument: the Request JSON string
Return value: the Response JSON string

For testing purposes the ‘OnRun’ trigger of the codeunit contains code that allows manual selection of a JSON Request file, calls the ‘CreateSalesOrders’ method to create data into NAV based on the Request Json string and then shows a message with the resulted JSON Response string.

Newton Json .Net library is used to parse the data from the json string.

The code inside Codeunit

Documentation()
// Andrei L - 2020-11-12

OnRun()
IF UPLOADINTOSTREAM('Select the file',  
                    'c:\temp',  
                    '',  
                     ClientFileName,  
                     InStr) THEN BEGIN  


  WHILE NOT InStr.EOS DO BEGIN
    InStr.READTEXT(Buffer);
    JSonText += Buffer;
  END;


  MESSAGE(JSonText); // --> Json Request
  MESSAGE(GetJson('CreateSalesOrders',JSonText)); // for testing purpose -->  Returns JsonResponse


END;


GetJson(Method : Text;Params : Text) : Text
IF Method = 'CreateSalesOrders' THEN BEGIN
  Result := CreateSalesOrders(Params);
  EXIT(Result);
END;


LOCAL CreateSalesOrders(Json : Text) ReturnJson : Text
JObject := JObject.Parse(Json);
ReturnJsonArr := ReturnJsonArr.JArray();


JArraySalesOrders := JArraySalesOrders.Parse(SelectJsonToken(JObject,'SalesOrders'));
FOR i := 0 TO JArraySalesOrders.Count - 1 DO BEGIN //process each sales order
  JObjectSalesOrder := JObjectSalesOrder.Parse(JArraySalesOrders.Item(i).ToString());
  CLEAR(SalesHeader);
  CreateSalesOrder(SalesHeader,JObjectSalesOrder,ReturnJsonArr); //create and Insert Sales Header
END;


ReturnJson := JsonConvert.SerializeObject(ReturnJsonArr);


LOCAL CreateSalesOrder(VAR SalesHeader : Record "Sales Header";JObjectSalesOrder : DotNet "Newtonsoft.Json.Linq.JObject";ReturnJsonArr : DotNet "Newtonsoft.Json.Linq.JArray")
// to do: validate data from Json is correct. If for example customer does not exist, Exit(false) and return an error in ReturnJson
SalesHeader.INIT;
SalesHeader.VALIDATE("Document Type",SalesHeader."Document Type"::Order);
SalesHeader.INSERT(TRUE); //generates Order No. using No. Series


CustomerNo := SelectJsonToken(JObjectSalesOrder,'CustomerNo');
// to do: if CustomerNo is invalid (for ex. does not exist) should exit function and create an error in the ReturnJson of the main CreateSalesOrder function: 
SalesHeader.VALIDATE("Sell-to Customer No.",CustomerNo);
IF EVALUATE(OrderDate,SelectJsonToken(JObjectSalesOrder,'OrderDate'),9) THEN
  SalesHeader.VALIDATE("Document Date",OrderDate);
SalesHeader.VALIDATE("External Document No.",SelectJsonToken(JObjectSalesOrder,'OrderNo'));
// to do: add more fields if needed
SalesHeader.MODIFY(TRUE);


//Results Log
JObject := JObject.JObject();
JObject.Add(JProperty.JProperty('OrderNo',SelectJsonToken(JObjectSalesOrder,'OrderNo')));
JObject.Add(JProperty.JProperty('NAVOrderNo',SalesHeader."No."));
JObject.Add(JProperty.JProperty('Result','Created'));


JArrayLines := JArrayLines.Parse(SelectJsonToken(JObjectSalesOrder,'SalesOrderLines'));
IF JArrayLines.Count > 0 THEN
  JArrReturnLines := JArrReturnLines.JArray();
FOR i := 0 TO JArrayLines.Count - 1 DO BEGIN
  JObjectSalesOrderLine := JObjectSalesOrderLine.Parse(JArrayLines.Item(i).ToString());
  LineNo += 10000;
  CreateSalesOrderLine(SalesHeader,SalesLine,LineNo,JObjectSalesOrderLine,JArrReturnLines);
END;


//Results Log
IF JArrReturnLines.Count > 0 THEN
  JObject.Add('OrderLines',JArrReturnLines);
ReturnJsonArr.Add(JToken.FromObject(JObject));


LOCAL CreateSalesOrderLine(SalesHeader : Record "Sales Header";SalesLine : Record "Sales Line";LineNo : Integer;JObjectSalesOrderLine : DotNet "Newtonsoft.Json.Linq.JObject";ReturnJArr : DotNet "Newtonsoft.Json.Linq.JArray")
// to do: add error handling in case one or more lines fails to be created.. We should show lines with errors in the ReturnJson of the main CreateSalesOrder function passed as argument from the main function
SalesLine.VALIDATE("Document Type",SalesHeader."Document Type");
SalesLine.VALIDATE("Document No.",SalesHeader."No.");
SalesLine."Line No." := LineNo;
SalesLine.VALIDATE(Type,SalesLine.Type::Item);
SalesLine.VALIDATE("No.",SelectJsonToken(JObjectSalesOrderLine,'ItemNo'));
SalesLine.VALIDATE("Location Code",SelectJsonToken(JObjectSalesOrderLine,'LocationCode'));
IF EVALUATE(Qty,SelectJsonToken(JObjectSalesOrderLine,'Quantity')) THEN
  SalesLine.VALIDATE(Quantity,Qty);
IF EVALUATE(UPrice,SelectJsonToken(JObjectSalesOrderLine,'UnitPrice')) THEN
  SalesLine.VALIDATE("Unit Price",UPrice);
SalesLine.INSERT(TRUE);


//Results Log
JObject := JObject.JObject();
JObject.Add(JProperty.JProperty('LineNo',FORMAT(SalesLine."Line No.")));
JObject.Add(JProperty.JProperty('Result','Created'));
ReturnJArr.Add(JToken.FromObject(JObject));


LOCAL SelectJsonToken(JObject : DotNet "Newtonsoft.Json.Linq.JObject";Path : Text) : Text
JToken := JObject.SelectToken(Path);
IF ISNULL(JToken) THEN
  EXIT('')
ELSE
  EXIT(JToken.ToString);

Explanation:

First we read the Array of Sales Orders
Next, for each Sales Order in this array, we Call function ‘CreateSalesOrder’
This function reads data about the Sales Order Header, populates nav fields and inserts a Sales Header record.
Then, it reads the SalesOrderLines array and if one or more elements are found, it gets data the array element and creates the Sales Order Lines in NAV.
Every time a Sales Header and a Sales Line is created, information is logged into the Response Json string.

Note: error handling was not implemented in this simple example, but can be easily done by following the logic of creating the Response data with information about what was created.

Real Life Implementation

All looks great until now, but how can this be used by the external application?

The best way is to create a ‘Middle Tier’ application that handles the authentication to NAV web service and calling the NAV method 'GetJson' with the 'Method' parameter and 'Request' JSON string provided by the external app. This can be done for example in .Net.

Result is for example REST method that can be called in a very easy way by the external application. Example of a method that creates a Released Production Order:

Conclusion

This is a pattern of working with JSON in Microsoft Dynamics NAV web services that we used with success in many implementations.