CHAPTER 9: DATAPORT AND XMLPORT CHANGES

Chapter 9: Dataport and XMLport Changes CHAPTER 9: DATAPORT AND XMLPORT CHANGES Objectives Introduction The objectives are: Provide an overview of dataport changes. Discuss changes in XMLport object and its new features. Dataport and XMLport are used to export and import data from and to Microsoft Dynamics NAV. Dataports are used with text files and XMLports are used with XML document files. These two objects have similarities on their purpose, to exchange information in and out of Microsoft Dynamics NAV. With the introduction of the new RoleTailored Client and the three-tier architecture, Microsoft DynamicsNAV 2009 will move toward XMLports. Dataports are still supported, but only in the Classic Client. The RoleTailored Client supports only XMLports as the way of exporting and importing data from and to Microsoft Dynamics NAV. 9-1

What s New for Microsoft Dynamics NAV 2009 Installation and Development Moving Forward with Dataports XMLport Changes Dataport as a way to export and import data from and to Microsoft Dynamics NAV is still supported in the Classic Client. In a traditional implementation, where only Classic Client is used, dataport is still used as usual. Transform Dataports to XMLports The RoleTailored client does not support dataport. In a dual client implementation, when both RoleTailored Client and Classic Client are used, XMLports are used as means of exporting and importing from and to Microsoft Dynamics NAV as dataports replacement. All dataports related features have to be modified to use XMLports. Existing dataports have to be migrated to XMLports to run on the new architecture. Unlike in form or report transformation, transforming dataport is a completely manual process. There is no automatic transformation tool available. To accommodate the use of XMLports to replace dataports, changes are made to XMLport objects. These changes include the following: Introduction of request page. New properties related to dataport. Execution in menu suite, RunObject property and RUN method. Together with these, additional features such as support for namespaces, and XML LAX, improve XMLport capabilities as a way of importing and exporting data in Microsoft Dynamics NAV 2009. Terminology Changes The following highlights terminology changes in XMLport object from earlier versions of Microsoft Dynamics NAV: Terminology To specify the name of an element or an attribute To specify whether data is of the type element or attribute Earlier version of Microsoft Dynamics NAV TagName TagType Microsoft Dynamics NAV 2009 NodeName NodeType 9-2

Chapter 9: Dataport and XMLport Changes Dataport Support The following new properties are introduced in XMLport objects in relation to dataports support: Name Type Location Description Format Option XMLport Determines the import/export format of the XMLport. It is added to support CSV export that is either a fixed length or a variable length. The options are as follows: XML Variable Text Fixed Text Width Integer Nodes (elements and/or attributes) Determines the width of the fixed width field. If Fixed Length is selected in the Format property, all elements and attributes of type Text and Field should have their Width property value set to more than 0, or it gives compilation errors. FieldDelimiter String XMLport Determines what the text delimiter is for a field. The default value is a quotation mark ( ). FieldSeparator String XMLport Determines what the field separator is for fields. The default value is a comma (,). RecordSeparator String XMLport Determines what the record separator is for records. The default value is <NewLine> TableSeparator String XMLport Determines what the table separator is for tables. The default value is <NewLine><NewLine> 9-3

What s New for Microsoft Dynamics NAV 2009 Installation and Development Request Page In addition to the new properties, request page is introduced for filtering purposes and additional input, before running XMLport. Generally, request pages in XMLports and request pages in reports are similar. They have similar filter functionality grouped in bands/fast tabs and an optional options band where developers add more controls. Request page in XMLport only has OK and Cancel buttons (compared to Print, Preview and Cancel buttons in request page in reports) regardless whether the XMLport is used for importing or exporting text or XML documents. The following shows a new property that is added for request page: Name Type Location Purpose UseRequestForm Boolean XMLport Determines whether a request page is used in the new RoleTailored Client. The default value is False. Direction property on the XMLport object is used instead of the Import property on the dataport object. This property is used to control whether direction control is shown on the request page and whether it controls the direction of the data (import/export). The following options are available, and show how they are related to dataport: Dataport XMLport Behavior <Yes> Default <Both> Default Direction control shown on request page instance.run run as import. Yes Import No control shown on the request page instance.run run as import. No Export No control shown on the request page instance.run run as export. The behavior in this table can change if currxmlport.importfile or import parameter on the static RUN is used. 9-4

Chapter 9: Dataport and XMLport Changes Execution In the earlier version of Microsoft Dynamics NAV, XMLports are run only from codeunits. In Microsoft Dynamics NAV 2009, XMLports can be run from: Menu suites designed for the RoleTailored Client. RunObject property of controls in page objects. Codeunits. An XMLport instance can be created as a variable of type XMLport and the instance has a RUN method, similar to the dataport RUN method. XML Schema Every XML attribute and XML element contains information about how they are expected inside the XMLport. For example: An attribute has Required property which tells whether the runtime should expect a value or not. An element contains information about its cardinality, governs by MinOccurs and MaxOccurs property, as illustrated in the following table. MinOccurs MaxOccurs Result Zero Once One element is allowed, but could be skipped. Once Once One element is required. Zero Unbounded Collection of elements, which can be empty. Once Unbounded Collection of elements, which cannot be empty. These properties are transformed into an XML XSD schema to let users validate XML input before the import. This schema can be used to validate the XML and construct classes that support and give programmatic interface to the XML. In Microsoft Dynamics NAV 2009 XMLport, it is possible to inline the schema inside the XML documents when exporting from the system. To enable this, a new property is introduced in the XMLport object: Name Type Location Remarks InlineSchema Boolean XMLport Adds the schema to all exported XML documents. The default value is No. 9-5

What s New for Microsoft Dynamics NAV 2009 Installation and Development Support for Namespaces A default namespace can be added and, or used during both import and export. This is important to support integration with other systems for the XML document to be in a specific namespace, to find its value. The following properties are introduced to support this new feature: Name Type Location Purpose UseDefaultNamespace Boolean XMLport Determines whether the value in DefaultNamespace property should be used as the default namespace for both output and input XML. The default value is False. DefaultNamespace String XMLport Determines the default namespace for both import and export. The default value is unique to individual XMLports. Example: urn:microsoftdynamicsnav/xmlports/x100 where 100 is the ID of the XMLport. XML LAX XML LAX is another new feature in XMLport in Microsoft Dynamics NAV 2009. When an XML document is passed between different systems, sometimes, one of the systems adds information to the XML document, which is irrelevant to the destination system. This information is typically added to the XML in another namespace. When the destination system tries to validate the XML document during its import, it will fail, because the XML document is not compliant with the XSD schema. Laxly schema definition (LAX) is an XML functionality used to define the allowance of XML which is not part of import and export. 9-6

Chapter 9: Dataport and XMLport Changes The following property is introduced to support XML LAX functionality: Name Type Location Purpose UseLax Boolean XMLport Determines whether LAX during import is accepted and updates the schema. The default value is False. FIGURE 9.1 SCHEMA SUPPORTING LAX In the previous example, before and after all elements, there is an added line: <xs:any minoccurs="0" maxoccurs="unbounded" namespace="##other" processcontents="lax" /> 9-7

What s New for Microsoft Dynamics NAV 2009 Installation and Development This line allows for one or more elements residing in a different namespace to be present in the XML document. FIGURE 9.2 EXAMPLE OF HOW TO USE LAX In the previous example, there is an added LAX XML schema element right after the element No. The usage can be seen in the bottom of the XML where an element named Error is added to the XML document, in another namespace. Without the LAX support, this would usually throw an invalid child element error. XML Standards XMLport in Microsoft Dynamics NAV 2009 abides to XML standards. The following shows examples for valid and invalid XML naming convention for elements and attributes: Example Valid/Invalid Explanation first.name Valid Dot (.) is valid within the name. résumé Valid Non-ASCII characters are valid. xml-tag Invalid Starts with xml. 123 Invalid Starts with a number. fun=xml Invalid = is invalid. my tag Invalid Contains white space xs:tag Invalid Contains : 9-8

Chapter 9: Dataport and XMLport Changes Summary XMLports replace dataports as the means of importing and exporting data to and from Microsoft Dynamics NAV 2009. This chapter discussed the changes in XMLport objects to support dataport functionalities and the new features of XMLports and properties introduced to support these features. 9-9

What s New for Microsoft Dynamics NAV 2009 Installation and Development Quick Interaction: Lessons Learned Take a moment and write down three key points you have learned from this chapter: 1. 2. 3. 9-10