Nav developer's blog : XML

Converting company names for NAV Web Services

scowri — Fri, 10 Jul 2009 21:26:00 GMT

A few weeks ago I saw an up tick in the number of cases having problems accessing exposed web service. Some of the problem has been because the “CRONUS USA, Inc.” company name converts to an unfamiliar “CROUNS_USA_x002C__Inc”. This will be changing in NAV 2009 SP1, but until that time it would be helpful to know exactly how company names are converted for NAV Web Services. The rules are:

The character '%' are converted to the word “Percent”.

The characters '@', '"', '.', '/', '(', ')', '\', '-', ' ' (blank space) are converted to “_” with the following two additional rules.

- no two succeeding “_”’s
- no trailing “_”

This covers most cases and only applies when replacing the above characters, not with the following "special characters".

Any remaining “special characters” are converted to “a valid XML name” (basically a numeric value, for example, the ampersand ‘&’ are converted to “_x0026_”). When a "special character" is converted like this, you could have two succeeding underscores ('_').

List of known special characters (please update as needed.):

The ampersand ‘&’ are converted to “_x0026_”
The comma ',' is converted to “_x002C_” (i.e. 'CRONUS USA, Inc.' would be converted to 'CRONUS_USA_x002C__Inc')

Additional, the How-To “Use SystemService to Find Companies” in the NAV 2009 Developer and IT Pro Documentation explain how to call the Companies operation on the SystemService to list the available companies with the converted names.

Scott Wright

Microsoft Dynamics North America

Microsoft Customer Service and Support (CSS) North America

These postings are provided "AS IS" with no warranties and confer no rights. You assume all risk for your use.

Customizing style sheets for MS Excel

jvukovic — Wed, 18 Feb 2009 12:59:00 GMT

As of version 5.0, Dynamics NAV introduced the option to export forms to MS Office (Word or Excel). Data presented on the form are exported in an xml, formatted using style sheets then sent to Word/Excel/Other programs

A Style Sheet tool for Dynamics NAV has later been released to help partners create custom style sheets for export to Word in an easy and user friendly way. A possibillity for extending functionality to export to Excel might be considered for future versions.

Meanwhile, customizing style sheets for excel, though requireing basic knowledge in xml and style sheets, can be simplified with some coding handling basic formatting of style sheets.

The FOB attached contains an example of how to create such a tool, allowing some basic customizations to excel style sheets.

Style Tool for Excel (xlt)

The Style Toos for EXceL (xlt) is designed to make it easier to customize style sheets for exporting to Excel. Style sheets have endless possibilities to format your Excel documents. This tool makes some of the most common possibilities simpler, but does not cover all possible changes, so it may not eliminate the need for editing style sheets in external tools, but may help you with some simple customizations.

Note, this tool was created and tested on 5.01 update 1 client, and assumes using default NavisionFormToExcel style sheet (update 1) as a starting point for customizations.

To use it with 5.0 client, you might need to modify the tool.

This is what you can achieve with xlt:
Define a (font) style to be used on document, for example Bold, color, underline, itallic, etc.
Define a style for certain condition, for example "Net Change" < 0, "Customer No." = 10000, etc
Add totals.

How to use xlt:
All functionality in the tool can be accessed from form 73000 "XLT Style Card". Run the form and insert a new record to create a new custom style sheet, and specify Code and Description.

Before you can make changes to a style sheet, you need to import it by clickin on Style -> Import, and choose an existing style sheet for export to Excel (such as NavisionFormToExcel), either from the database or from a file.

On the Destination tab, specify the table and form IDs that the style sheet will be used for.

Example:
Run form 73000 and press F3. Fill out Code:ChartOfAccounts, Description: export Chart of Accounts
Import the standard NavisionFormToExcel style sheet (by default placed in <client folder>\Stylehseets), by clicking on Style-Import and selecting NavisionFormToExcel style sheet.
In New XSLT file location field, specify the location of your customized style sheet (example: c:\temp\NewXsltFIleName.xslt).
On Destination tab, specify TableID=15, select 'Style sheet for this form only' and select form 16, Chart of Accounts.

Excel Styles:
You are now ready to customize your style sheet. To create new style, click Design -> Excel Styles. This shows you the styles that were imported with the standard style sheet. From here you can modify existing, or create new ones. To create a new style, press F3, and enter a Style ID.
Then click on "Edit in Excel (F9)" to define this new style. It will open up Microsoft Excel, and here you can apply any formatting you wish, TO THE TOP LEFT CELL. The style you apply to this cell and it's contents will be imported and applied to all the cells your style applies to. Once you are done applying your style, close and save Excel, and then go back to NAV and confirm to import the style.

As an example, consider the following scenario: we want to modify the existing label (caption) style and also create a new style (red fonts) that we apply to records in Net Change column with negative value.
To modify existing label style, click on Design-Excel Styles, press Page Up/Down to browse between records, find Style ID: Label and Press F9 (Edit in excel). In opened excel ark, go to top left cell, in Excel menu select Home-Font and select a different font (for example, Arial Black, size 14). Change also the color to blue. Close the excel and save the file. In NAV client, click on YEs on prompted question (Please apply format in Excel sheet.....). In the Style tab, check that new style is applied (you should see the record with Option=Font, Property=ss:FontName and Value=Arial Black).

You can apply same kind of change directly in the Style tab (instead of opening Excel), provided you are familiar with properties and values as defined in Excel. If modifying styles directly in Style tab, remember to click 'Update (F11)' to apply changes to style sheet.

Note that

1) moving away from the style by closing the form or moving to the next record will not save any changes you made manually (and not through excel), and

2) the tool does not validate if changes you do manually are valid.

Now we want to create a new style and apply it to Net Change column of records with net change < 0.
Press F3 to create a new style, in Style ID field type RED. Click on F9 (Edit in Excel) and in opened excel sheet click on top left cell. In Excel menu, select Home-Font and select red font color. Close the Style Sheet, answer yes to save changes. In NAV Client answer yes to prompted question (Please apply format in Excel Sheet...). In General tab, You should now see properties defined for StyleID=RED

Conditional formatting:
After designing the style(s), then go back to the XLT Style card, and then click Design -> "Conditional Formatting" to apply this style to certain conditions. It is not recommended that you change any of the existing layouts here, but you can create a new one by clicking "Insert (F3)". This opens a mini-wizard where you can specify which columns and values this will apply to.

To follow our example, we will now specify the condition for using the style created in last step, RED style.
Close the Excel Styles form and in Xslt style card click on Design-Conditional Formatting. Click on F3 (or click on Insert) to create new condition (it is not recommended to modify any of the existnig, defualt ones). Wizard form opens. We will now create a condition to apply style red to NET Change column with values < 0. Select TableID=15 and Field 32 (Net Change). In Condition field, select'<' anad Value=0. Finally, In Choose style select RED. Click on Finish. You should now see your condition defined in General tab. Condition= (@name='Net Change') and (@value<'0').
Click on Update to update the style sheet with new condition.

Totals
You can specify fields that you want to create totals for, by clicking on Design -> "Total Fields", and select one or more (numerical!) fields. You also need to add one line of C/AL code in codeunit 403 "Application Launch Management". The following line should be added to Codeunit 403, at the top of function LanuchApp:

XLStyleSheetDataMgt.UpdateDataXML(DataXML,StylesheetID);

where XLStyleSheetDataMgt is a new local variable, type Codeunit, subtype 73001 ("XLT Style Sheet Data Mgt")

This will add totals to the data that you export to Excel, and it will add elements to the style sheet to handle these totals. Note: This will not work for RTC because RTC does not make calls to codeunit 403 (see blog here: http://blogs.msdn.com/nav_developer/archive/2008/12/16/dynamics-nav-2009-and-ms-office-integration-send-to-excel-and-word.aspx).

Export style sheet:
When you have created one or more style(s) and applied them to certain conditions, then you generate a new style sheet from the "XLT Style Card" by clicking Style -> Export, and then select to export to file or database. If exporting to database, then a new style sheet will be saved in database, using the Description you have specified in the "XLT Style Card".

Open form 18 (Chart of Accounts), in toolbar menu, click on send-to button. Select Microsoft Excel and select 'export Chart of Accounts' style sheet., click on OK.
Chart of Accoutns shoud lbe exported to excelm, with labels in Arial Black font, size 14. Net change column where value < 0 should be marked RED and totals should be present for Net Change column.

Other functionality:
- From "XLT Style Card", tab "Standard Styles", specify a style to apply to totals.
- Click Style -> Reset to re-load the stylesheet, which will erase any changes you have done since you imported it.

These postings are provided "AS IS" with no warranties and confer no rights. You assume all risk for your use.

All feedback regarding issues or suggestion to this tool are very welcome!

Jasminka Vukovic, Lars Lohndorf-Larsen

Microsoft Dynamics NO

Microsoft Customer Service and Support (CSS) EMEA

Sample of how to read a simple XML document using MSXML DOM in NAV

Lohndorf — Mon, 31 Mar 2008 15:15:00 GMT

This is a follow-up to the post "how to write a simple XML document". The other post conitains a few more background details which I won't repeat here. So even if you only want to read XML Documents, then you may want to have a look there anyway.

But let's get straight to the point. This is how you can read an XML Document from Microsoft Dynamics NAV, using MSXML DOM:

1. Create a new codeunit.

2. Declare these 5 new global variables:

XMLDoc Type = Automation 'Microsoft XML, v4.0'.DOMDocument
DOMNode Type = Automation 'Microsoft XML, v4.0'.IXMLDOMNode
XMLNodeList Type = Automation 'Microsoft XML, v4.0'.IXMLDOMNodeList

CurrentElementName Type = Text 30
i Type = Integer

3. Initialize the Dom Document:
CREATE(XMLDoc);
XMLDoc.async(FALSE);
XMLDoc.load('C:\XML\MyXML.xml');

4. Set up a loop to browse through the nodes in the document:
XMLNodeList := XMLDoc.childNodes;
for i := 0 to XMLNodeList.length - 1 do begin
DOMNode := XMLNodeList.item(i);
ReadChildNodes(DOMNode);
end;

You also have to create ReadChildNodes as a function with one parameter:
CurrentXMLNode, Type = Automation 'Microsoft XML, v4.0'.IXMLDOMNode.

The reason for the functionis to enable you to run it recursively. This is useful because you don't know how many child nodes there are. And there can easily be a child node inside of another child node.

So create the function ReadChildNodes.
The function has one parameter:
CurrentXMLNode : Automation "'Microsoft XML, v4.0'.IXMLDOMNode"

And a number of local variables:
TempXMLNodeList   Automation = 'Microsoft XML, v4.0'.IXMLDOMNodeList
TempXMLAttributeList   Automation = 'Microsoft XML, v4.0'.IXMLDOMNamedNodeMap
j   Integer
k   Integer

The function checks to see what type of node it was called with. A node can be an element, text (data), attribute etc. The node property .nodeType tells you which it is. See the documentation (included in MSXMLSDK) for a complete list of possible nodeTypes.

This is the function:

ReadChildNodes(CurrentXMLNode : Automation "'Microsoft XML, v4.0'.IXMLDOMNode")
CASE FORMAT(CurrentXMLNode.nodeType) OF

'1': // Element
BEGIN
    // Global variable CurrentElementName to keep track of what node
    // we are currently processing
    CurrentElementName := CurrentXMLNode.nodeName;

    // Process Attributes
    // If the element has attributes, then browse through those.
    TempXMLAttributeList := CurrentXMLNode.attributes;
    FOR k := 0 TO TempXMLAttributeList.length - 1 DO
      ReadChildNodes(TempXMLAttributeList.item(k));

    // Process Child nodes
    TempXMLNodeList := CurrentXMLNode.childNodes;
    FOR j := 0 TO TempXMLNodeList.length - 1 DO
      ReadChildNodes(TempXMLNodeList.item(j));
END;

'2': // Attribute
BEGIN
MESSAGE(CurrentElementName + ' Attribute : ' +
FORMAT(CurrentXMLNode.nodeName) + ' = ' + FORMAT(CurrentXMLNode.nodeValue));
END;

'3': // Text
BEGIN
MESSAGE(CurrentElementName + ' = ' + FORMAT(CurrentXMLNode.nodeValue));
END;
END;

Now, try to run the codeunit against any XML document, and it will give a MESSAGE for each node and each attribute. This codeunit can be used for scanning any XML document from begin to end.

Next example:

Now, lets say you are looking for specific nodes in an XML document. As an example, take this document:

- <Document>

- <Order ID="1001">

- <Line>

10000

</Line>

- <Line>

20000

</Line>

</Order>

- <Order ID="1002">

- <Line>

10000

</Line>

- <Line>

20000

</Line>

- <Line>

30000

</Line>

</Order>

</Document>

One of the good things in MSXML DOM is, that it reads the whole document into memory, so you can jump between nodes, and browse them, and select sub-sets based on node names. So you do not have to read a document from top to bottom if you know exactly which parts of the document you are interested in.

First, we can count how many orders the document contains (see how many "Order"-elements are under the root-element):

OnRun()
CREATE(XMLDoc);
XMLDoc.async(FALSE);
XMLDoc.load('C:\XML\Order.xml');

XMLNodeList := XMLDoc.getElementsByTagName('Document/Order');
MESSAGE('The document has %1 elements called Order',XMLNodeList.length);

This will open the XML document, then use the getElementsByTagName-function to get all elements that match the tag name. Note that the tag name you specify is case sensitive (like everything else in XML)! So in this case, it would not find elements called "order".

Once you have the XMLNodeList, then you can go through the nodes in that list, using the first example.

Finally, an example which will read the XML document shown above, and show an Amount-total for each order:

OnRun()
CREATE(XMLDoc);
XMLDoc.async(FALSE);
XMLDoc.load('C:\XML\Order.xml');

XMLNodeList := XMLDoc.getElementsByTagName('Document/Order');
FOR i := 0 TO XMLNodeList.length - 1 DO BEGIN
NumberDecTotal := 0;
DOMNode := XMLNodeList.item(i);
XMLNodeList2 := DOMNode.selectNodes('Line/Amount');
FOR j := 0 TO XMLNodeList2.length - 1 DO BEGIN
    DOMNode2 := XMLNodeList2.item(j);
    NumberAsText := FORMAT(DOMNode2.text);
    EVALUATE(NumberDec,NumberAsText);
    NumberDecTotal := NumberDecTotal + NumberDec;
END;
MESSAGE('Order has total amount of %1.',NumberDecTotal);
END;

This example uses DomNode.SelectNodes, which will select all matching nodes. If you are looking for an individual node, then you can use DomNode.selectSingleNode which will only return one node (the first that matches).

In an XML document, everything is Text. So you have to convert to numbers where needed. Final note: Make sure to make your code more robust than this! What if Amount contains a character? What if an element is missing? If you don't take these things into consideration, then your code can fail with very unfriendly errors.

These postings are provided "AS IS" with no warranties and confer no rights. You assume all risk for your use.

Best regards

Lars Lohndorf-Larsen

Microsoft Dynamics UK

Microsoft Customer Service and Support (CSS) EMEA

Sample of how to write a simple XML document using MSXML DOM in NAV

Lohndorf — Mon, 31 Mar 2008 14:59:00 GMT

This post if for when you need to export data in the form of XML from Microsoft Dynamics NAV. If you are not familiar with how to program with MSXML DOM, then it can take a lot of time and work to create even a simple XML document. The purpose of this post is to show a simple example, and to get you started programming with MSXML DOM from NAV.

I have split this into two posts: "How to write" (this post), and "How to read" an XML Document (click here), since the methods and functions used are quite different.

Why not just use XML-Ports? You can of course, but then you limit yourself to the functionality and limitations that exist in XML-Ports. An example of a limitation in XML-Ports is that they do not support namespaces. If you think that one day you may need functionality that is not supported by XML-Ports, and for which you have to use MSXML DOM anyway, then consider to just use MXSML DOM from the start. It is more complex to begin with, but once you have a set of functions to add / search etc elements in an XML document, then it does not have to be much more complex than using XML-Ports. Note that it is not possible to access an XML docuemnt via MSXML DOM from an XML-Port while the XML-Port is accessing it. The two methods are mutually exclusive.

An XML document is organized as a heararchy of elements, and everything (elements and data) gets added piece by piece to existing elements.

Let's get started with the simplest possible XML DOcument:

Create a new codeunit with 3 variables:
Name     DataType Subtype Length
XMLDoc     Automation 'Microsoft XML, v4.0'.DOMDocument
DOMNode     Automation 'Microsoft XML, v4.0'.IXMLDOMNode
DomTextNode     Automation 'Microsoft XML, v4.0'.IXMLDOMText

In this example I use MSXML version 4, but you can use version 5 or 6 if you prefer. Version 4 is mostly used because it most likely contains all the functionality you will need, and it will be backward compatible to more machines - even old ones.

Initialize the document:

OnRun()
CREATE(XMLDoc);
XMLDoc.async(FALSE);

Unless you have specific reasons not to, set asynch = FALSE. Especially when you are reading an XML document. It means that it will load the whole document into memory before it starts reading through it. If you don't set this property, you may begin to process the document before it is completely loaded into memory.

Now create a new node, and then add it to the document:

DOMNode := XMLDoc.createNode(1,'NodeName','');
XMLDoc.appendChild(DOMNode);

Then add some data. This is done in the same way as you add an element: Creat the element first, and then add it to the right place in the document:

DOMTextNode := XMLDoc.createTextNode('NodeValue');
DOMNode.appendChild(DOMTextNode);

You can add any additional elements like this: Creat the element of the type that you need (node, text, attribute etc), and then append it to the document.

To see the document, save it to disk:
XMLDoc.save('C:\XML\MyXML.xml');

Note: If you run on Vista, it might not allow you to save files on the root of the c: drive. So create a new folder, for example c:\XML\

Then run this codeunit. You should get a very simple document like this:
<NodeName>NodeValue</NodeName>

If you want to add further nodes to this document then repeat the steps above to create a new node, then append it to an existing node. For example, to add a new node:

Create a new variable:
NewDOMNode : 'Microsoft XML, v4.0'.IXMLDOMNode

Initialize the new node:
NewDOMNode := XMLDoc.createNode(1,'NewNode','');
DOMNode.appendChild(NewDOMNode);

And add text to the new node:
DOMTextNode := XMLDoc.createTextNode('NewNodeValue');
NewDOMNode.appendChild(DOMTextNode);

Now, your xml document will look like this:

- <NodeName>

NodeValue

<NewNode>NewNodeValue</NewNode>

</NodeName>

Adding namespace and Attributes:

You can add a name space either to the whole document, or to individual nodes. To add a name space to the document, go back to the relevant line above, and specify the 3rd parameter:

DOMNode := XMLDoc.createNode(1,'NodeName','MyNameSpace');

Finally, adding an attribute to a node is similar to adding a text element: Initialize the Attribute, then add it to the relevant node. Use the function SetNamedItem to add attributes. Let's add an attribute called ID with the value 10000:

Create a new Automation variable:
XMLAttributeNode : 'Microsoft XML, v5.0'.IXMLDOMAttribute

Initialize the attribute, then add it to the node:
XMLAttributeNode := XMLDoc.createAttribute('ID');
XMLAttributeNode.value := '10000';
DOMNode.attributes.setNamedItem(XMLAttributeNode);

The whole codeunit should now look like this:

// Initialize the document
CREATE(XMLDoc);
// Create Node and attach it to the document. Use name space MyNameSpacefunction
DOMNode := XMLDoc.createNode(1,'NodeName','MyNameSpace');
XMLDoc.appendChild(DOMNode);

// Add data (text) to the node
DOMTextNode := XMLDoc.createTextNode('NodeValue');
DOMNode.appendChild(DOMTextNode);

// Add an attribute to the node
XMLAttributeNode := XMLDoc.createAttribute('ID');
XMLAttributeNode.value := '10000';
DOMNode.attributes.setNamedItem(XMLAttributeNode);

// Initialize a new node:
NewDOMNode := XMLDoc.createNode(1,'NewNode','');
DOMNode.appendChild(NewDOMNode);

// And add text to the new node:
DOMTextNode := XMLDoc.createTextNode('NewNodeValue');
NewDOMNode.appendChild(DOMTextNode);

// Finally, save the document for viewing:
XMLDoc.save('C:\XML\MyXML.xml');

Further references:

MSXML is further documented in MSXML Software Development Kit (MSXMLSDK). I would recommend that you download this to have the online help available for all of the MSXML DOM functions.

These postings are provided "AS IS" with no warranties and confer no rights.
You assume all risk for your use.

Lars Lohndorf-Larsen

Microsoft Dynamics UK
Microsoft Customer Service and Support (CSS) EMEA