XMLports

XML is eXtensible Markup Language, a structured text format developed to describe data to be shared by dissimilar systems. XML has become a default standard for communications between systems. To make handling XML-formatted data simpler and more error resistant, NAV provides XMLports, a data import/export object. In addition to processing XML-formatted data, XMLports can also handle a wide variety of other text file formats (including CSV files, generic flat files, and so on). XML formatted data is text based, with each piece of information structured in one of two basic formats, Elements or Attributes. An Element is the overall logical unit of information while an Attribute is a property of an Element. They are formatted as follows:

  • <Tag>element value</Tag> (an Element format)
  • <Tag AttribName = "attribute data value"> (an Attribute format)

Elements can be nested, but must not overlap. Element and Attribute names are case-sensitive. Names cannot start with a number, punctuation character, or the letters "xml" (or XML, and such). Also, they cannot contain spaces.

An Attribute value must always be enclosed in single or double quotation marks. Some references suggest that Elements should be used for data and Attributes for metadata. Complex data structures are built up of combinations of these two formats.

For example:

<Table Name='Sample XML format'>
   <Record>
      <DataItem1>12345</DataItem1>
      <DataItem2>23456</DataItem2>
   </Record>
   <Record>
      <DataItem1>987</DataItem1>
   </Record>
   <Record>
      <DataItem1>22233</DataItem1>
      <DataItem2>7766</DataItem2>
   </Record>
</Table>

In this case, we have a set of data identified as a Table with an attribute of Name equal to 'Sample XML format', which contains three Records, each Record containing data in one or two fields named DataItem1 and DataItem2. The data is in a clearly structured text format so it can be read and processed by any system prepared to read this particular XML format. If the field tags are well designed, the data is easily interpretable by humans as well. The key to successful exchange of data using XML is the sharing and common interpretation of the format between the transmitter and the recipient.

XML is a standard format in the sense that the data structure options are clearly defined. But it is very flexible in the sense that the identifying tag names in < > brackets and the related data structures that can be defined and handled are totally open-ended. The specific structure and the labels are whatever the communicating parties decide they should be. The "rules" of XML only determine how the basic syntax shall operate.

XML data structures can be as simple as a flat file consisting of a set of identically formatted records or as complex as a sales order structure with headers containing a variety of data items, combined with associated detail lines containing their own variety of data items. An XML data structure can be as complicated as the application requires.

XML standards are maintained by the W3C whose web site is http://www.w3.org/. There are many other useful web sites for basic XML information.

XMLport components

Although in theory XMLports can operate in both an import and an export mode, in practice, individual XMLport objects tend to be dedicated to either import or export. This allows the internal logic to be simpler. XMLports utilize a process of looping through and processing data similar to that of Report objects.

The components of XMLports are:

XMLport components

XMLport properties

XMLport properties are shown in the following screenshot of the Properties of the XMLport object 9170:

XMLport properties

Descriptions of the individual properties follow:

  • ID: The unique XMLport object number.
  • Name: The name by which this XMLport is referred to within the C/AL code.
  • Caption: The name that is displayed for the XMLport; it defaults to the contents of the Name property.
  • CaptionML: The Caption translation for a defined alternative language.
  • Direction: This defines whether this XMLport can only Import, Export, or <Both>; the default is <Both>.
  • DefaultFieldsValidation: This defines the default value (Yes or No) for the FieldValidate property for individual XMLport data fields. The default for this field is Yes, which would in turn set the default for individual field FieldValidate properties to Yes.
  • Encoding (or TextEncoding): This defines the character encoding option to be used – UTF-8 (ASCII compatible), UTF-16 (not ASCII compatible), or ISO-8859-2 (for certain European languages written in Latin characters). UTF-16 is the default. This is inserted into the heading of the XML document.

    The TextEncoding option is only available if the Format property is Fixed Text or Variable Text. In this case, a character coding option of MS-DOS is available and is the default.

  • XMLVersionNo: This defines to which version of XML the document conforms, Version 1.0 or 1.1. The default is Version 1.0. This is inserted into the heading of the XML document.
  • Format/Evaluate: This can be C/SIDE Format/Evaluate (the default) or XML Format Evaluate. This property defines whether the external text data is (for imports) or will be (for exports) XML data types or C/SIDE data types. Default processing for all fields in each case will be appropriate to the defined data type. If the external data does not fit in either of these categories, then the XML data fields must be processed through a temporary table. First, a temporary table is defined with a suitable number and size text data fields. Second, the external data is read into those text data fields. Finally, data conversion logic converts the data to C/AL compatible data types which can be stored in the NAV database. Very limited additional information on this is available in the online Help in Temporary Property (XMLports).
  • UseDefaultNamespace and DefaultNamespace: These properties are provided to support compatibility with other systems that require the XML document to be in a specific namespace, such as use of a web service as a reference within Visual Studio. UseDefaultNamespace defaults to No. A default namespace in the form of URN (Uniform Resource Name or, in this case, a Namespace Identifier) concluding with the object number of the XMLport is supplied for the DefaultNamespace property. This property is only active if the Format property is XML.
  • InlineSchema: This property defaults to No. An inline schema allows the XML schema document (an XSD) to be embedded within the XML document. This can be used by setting the property to Yes when exporting an XML document, which will add the schema to that exported document. This property is only active if the Format property is XML.
  • UseLax: This property defaults to No. Some systems may add information to the XML document, which is not defined in the XSD schema used by the XMLport. When this property is set to Yes, that extraneous material will be ignored, rather than resulting in an error. This property is only active if the Format property is XML.
  • Format: This property has the options of XML, Variable Text, or Fixed Text. It defaults to XML. This property controls the import/export data format that the XMLport will process. Choosing XML means that the processing will only deal with a properly formatted XML file. Choosing Variable Text means that the processing will only deal with a file formatted with delimiters set up as defined in the FieldDelimiter, FieldSeparator, RecordSeparator, and TableSeparator properties (such as CSV files). Choosing Fixed Text means that each individual element and attribute must have its Width property set to a value greater than 0 (zero) and the data to be processed must be formatted accordingly. If enabled, these four fields can also be changed programmatically from within the C/AL code.
  • FileName: This can be filled with the predefined path and name of a specific external text data file to be either the source (for Import) or target (for Export) for the run of the XMLport, or this property can be set dynamically. Only one file at a time can be opened, but the file in use can be changed during the execution of the XMLport (not often done).
  • FieldDelimiter: This applies to the Variable Text format external files only. It defaults to <">—double quote, the standard for so-called "comma-delimited" text files. This property supplies the string that will be used as the starting delimiter for each data field in the text file. If this is an Import, then the XMLport will look for this string, and then use the following string as data until the next FieldDelimiter string is found, terminating the data string. If this is an Export, the XMLport will insert this string at the beginning and end of each data field contents string.
  • FieldSeparator: This applies to the VariableText format external files only. Defaults to <,>—a comma, the standard for so-called "comma delimited" text files. This property supplies the string that will be used as the delimiter between each data field in the text file (looked for on Imports and inserted on Exports). See the Help for this property for more information.
  • RecordSeparator: This applies to the VariableText or FixedText format external files only. This defines the string that will be used as the delimiter at the end of each data record in the text file. If this is an Import, the XMLport will look for this string to mark the end of each data record. If this is an Export, the XMLport will append this string at the end of each data record output. The default is <<NewLine>>, which represents any combination of CR (carriage return—ASCII value 13) and LF (line feed—ASCII value 10) characters. See the Help for this property for more information.
  • TableSeparator: This applies to the VariableText or FixedText format external files only. This defines the string that will be used as the delimiter at the end of each Data Item (for example, each text file). The default is <<NewLine><NewLine>>. See the Help for this property for more information.
  • UseRequestForm: This determines whether a Request Page should be displayed to allow the user choice of Sort Sequence, entry of filters, and other requested control information. The options are Yes and No. The default is <Yes>. An XMLport Request Page has only the OK and Cancel options.
  • TransactionType: This property identifies the XMLport processing Server Transaction Type as Browse, Snapshot, UpdateNoLocks, or Update. This is an advanced and seldom-used property. For more information, we can refer to the Help files and SQL Server documentation.
  • Permissions: This property provides report-specific setting of permissions, which are rights to access data, subdivided into Read, Insert, Modify, and Delete. This allows the developer to define permissions that override the user-by-user permissions security setup.

XMLport triggers

The XMLport has a very limited set of triggers, which are listed next:

  • Documentation() is for documentation comment
  • OnInitXMLport() is executed once when the XMLport is loaded before the table views and filters have been set
  • OnPreXMLport() is executed once after the table views and filters have been set. Those can be reset here
  • OnPostXMLport() is executed once after all the data is processed, if the XMLport completes normally

XMLport data lines

An XMLport can contain any number of data lines. The data lines are laid out in a strict hierarchical structure, with the elements and attributes mapping exactly, one for one, in the order of the data fields in the external text file, the XML document.

XMLports should not be run directly from a Navigation Pane action command (due to conflicts with NAV UX standards), but can be run either from ribbon actions on a Role Center or other page, or by means of an object containing the necessary C/AL code. When running from another object (as opposed to running from an action menu entry), the C/AL code calls the XMLport to stream data either to or from an appropriately formatted file (XML document or other text format). This calling code is typically written in a Codeunit, but can be placed in any object that can contain the C/AL code.

The following example code executes an exporting XMLport and saves the resulting file from the NAV service tier to the client machine:

XMLfile.CREATE(TEMPORARYPATH + 'RadioShowExport.xml');
XMLfile.CREATEOUTSTREAM(OutStreamObj);
XMLPORT.EXPORT(50000,OutStreamObj);
FromFileName := XMLfile.NAME;
ToFileName := 'RadioShowExport.xml';
XMLfile.CLOSE;

//Need to call DOWNLOAD to move the xml file
//from the service tier to the client machine
DOWNLOAD(FromFileName,'Downloading File...','C:','Xml file(*.xml)|*.xml',ToFileName);

//Make sure to clean up the temporary file from the 
//service tier
ERASE(FromFileName);

Two text variables (the "from" file name and "to" file name), a file variable, and an OutStream object variable are required to support the preceding code. The data variables are defined as shown in the following screenshot:

XMLport data lines

XMLport line properties

The XMLport line properties which are active on a line depend on the contents of the SourceType property. The first four properties listed are common to all three SourceType values (Text, Table, and Field) and the other properties specific to each are listed below the screenshots showing all the properties for each SourceType.

  • Indentation: This indicates at what subordinate level in the hierarchy of the XMLport this entry exists. Indentation 0 is the primary level, parent to all higher numbered levels. Indentation 1 is a child of indentation 0, indentation 2 is a child of 1, and so forth. Only one Indentation 0 is allowed in an XMLport, so often we will want to define the Level 0 line to be a simple text element line. This allows the definition of multiple Tables at Indentation level 1.
  • NodeName: This defines the Node Name that will be used in the XML document to identify the data associated with this position in the XML document. No spaces are allowed in a NodeName; we can use underscores, dashes, and periods but no other special characters.
  • NodeType: This defines if this data item is an Element or an Attribute.
  • SourceType: This defines the type of data this field corresponds to in the NAV database. The choices are Text, Table, and Field. Text means that the value in the SourceField property will act as a Global variable and, typically must be dealt with by embedded C/AL code. Table means that the value in the SourceField property will refer to a NAV table. Field means that the value in the SourceField property will refer to a NAV field within the parent table previously defined as an element.

SourceType as Text

The following screenshot shows the properties for SourceType as Text:

SourceType as Text

The description of the Text-specific properties is as follows:

  • TextType: This defines the NAV Data Type as Text or BigText. Text is the default.
  • VariableName: This contains the name of the Global variable, which can be referenced by the C/AL code.

The Width, MinOccurs, and MaxOccurs properties are discussed later in this chapter.

SourceType as Table

The following screenshot shows the properties for SourceType as Table:

SourceType as Table

The descriptions of the table-specific properties are as follows:

  • SourceTable: This defines the NAV table being referenced.
  • VariableName: This defines the name to be used in the C/AL code for the NAV table. This is the functional equivalent to definition of a Global variable.
  • SourceTableView: This enables the developer to define a view by choosing a key and sort order or by applying filters on the table.
  • ReqFilterHeading and ReqFilterHeadingML: These fields allow the definition of the name of the Request Page filter definition tab that applies to this table.
  • CalcFields: This lists the FlowFields in the table that are to be automatically calculated.
  • ReqFilterFields: This lists the fields that will initially display on the Request page filter definition tab.
  • LinkTable: This allows the linking of a field in a higher-level item to a key field in a lower-level item. If, for example, we were exporting all the Purchase Orders for a Vendor, we might Link the Buy-From Vendor No. in a Purchase Header to the No. in a Vendor record. The LinkTable in this case would be Vendor and LinkField would be No.; therefore LinkTable and LinkFields work together. Use of the LinkTable and LinkFields operates the same as applying a filter on the higher-level table data so that only records relating to the defined lower-level table and field are processed. See the Help for more detail.
  • LinkTableForceInsert: This can be set to force the insertion of the linked table data and execution of the related OnAfterInitRecord() trigger. This property is tied to the LinkTable and LinkFields properties. It also applies to Import.
  • LinkFields: This defines the fields involved in a table + field linkage.
  • Temporary: This defaults to No. If this property is set to Yes, it allows the creation of a Temporary table in working storage. Data imported into this table can then be evaluated, edited, and manipulated before being written out to the database. This Temporary table has the same capabilities and limitations as a Temporary table defined as a Global variable.
  • AutoSave: If set to Yes (the default), an imported record will be automatically saved to the table. Either AutoUpdate or AutoReplace must also be set to Yes.
  • AutoUpdate: If a record exists in the table with a matching primary key, all the data fields are initialized, and then all the data from the incoming record is copied into the table record.
  • AutoReplace: If a record exists in the table with a matching primary key, the populated data fields in the incoming record are copied into the table record; all the other fields in the target record are left undisturbed. This provides a means to update a table by importing records with a limited number of data fields filled in.

The Width, MinOccurs, and MaxOccurs properties are discussed later in this chapter.

SourceType as Field

The following screenshot shows the properties for SourceType as Field:

SourceType as Field

The description of the Field-specific properties is as follows:

  • SourceField: This defines the data field being referenced. It may be a field in any defined table.
  • FieldValidate: This applies to Import only. If this property is Yes, then whenever the field is imported into the database, the OnValidate() trigger of the field will be executed.
  • AutoCalcField: This applies to Export and FlowField Data fields only. If this property is set to Yes, the field will be calculated before it is retrieved from the database. Otherwise, a FlowField would export as an empty field.

The details of the Width, MinOccurs, and MaxOccurs properties follow in the next section.

The Element or Attribute

An Element data item may appear many times but an Attribute data item may only appear at most once; the occurrence control properties differ based on the NodeType.

NodeType of Element

The Element-specific properties are as follows:

  • Width: When the XMLport Format property is Fixed Text, then this field is used to define the fixed width of this element's field.
  • MinOccurs: This defines the minimum number of times this data item can occur in the XML document. This property can be Zero or Once (the default).
  • MaxOccurs: This defines the maximum number of times this data item can occur in the XML document. This property can be Once or Unbounded. Unbounded (the default) means any number of times.

NodeType of Attribute

The Attribute-specific property is as follows:

  • Occurrence: This is either Required (the default) or Optional, depending on the text file being imported

XMLport line triggers

The XMLport line triggers are shown in the following screenshot for the three line Source types: Profiles (Text), Profile (Table), and ID (Field):

XMLport line triggers

As we can see in the preceding screenshot, there are different XMLport triggers depending on whether DataType is Text, Table, or Field.

DataType as Text

The triggers for DataType as Text are:

  • Export::onBeforePassVariable(), for Export only: This trigger is typically used for manipulation of the text variable.
  • Import::OnAfterAssignVariable(), for Import only: This trigger gives us access to the imported value in text format.

DataType as Table

The triggers for DataType as Table are as follows:

  • Import::OnAfterInsertRecord(), for Import only: This trigger is typically used when the data is being imported into Temporary tables. This is where we would put the C/AL code to build and insert records for the permanent database table(s).
  • Import::OnBeforeModifyRecord(), for Import only: This trigger is for use when AutoSave is Yes, to update the imported data before saving it.
  • Import::OnAfterModifyRecord(), for Import only: This trigger is for use when AutoSave is Yes, to update the data after updating.
  • Export::OnPreXMLItem(), for Export only: This trigger is typically used for setting filters and initializing before finding and processing the first database record.
  • Export::OnAfterGetRecord(), for Export only: This trigger allows access to the data after the record is retrieved from the NAV database. It is typically used to allow manipulation of table fields being exported.
  • Import::OnAfterInitRecord(), for Import only: This trigger is typically used to check whether or not a record should be processed further or to manipulate the data.
  • Import::OnBeforeInsertRecord(), for Import only: This is another place where we can manipulate data before it is inserted into the target table. This trigger is executed after the OnAfterInitRecord() trigger.

DataType as Field

The triggers for DataType as Field are as follows:

  • Import::OnAfterAssignField(), for Import only: This trigger provides access to the imported data value for evaluation or manipulation before outputting to the database.
  • Export::OnBeforePassField(), for Export only: This trigger provides access to the data field value just before the data is exported.

XMLport Request Page

XMLports can also have a Request Page to allow the user to enter Option control information and filter the data being processed. Default filter fields that will appear on the Request Page are defined in the Properties form for the table XMLport Line.

Any desired options that are to be available to the user as part of the Request Page must be defined in the Request Options Page Designer. This Designer is accessed from the XMLport Designer through View | Request Page. The definition of the contents and layout of the Request Options Page is done in essentially the same way as other pages are done. As with any other filter setup screen, the user has complete control of what fields are used for filtering and what filters are applied.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset