If you haven’t already read part 1 you should do so here, before continuing to read this post.
You have seen how to use an XMLPort in a Web Service without any line of code. That was amazing, wasn’t it? Now, how was this possible?
The answer is really simple: because the XMLPort parameter is a VAR parameter (e.g. ByRef). As you know a VAR parameter in C/AL means that the parameter value can be changed by the function and the changed value will be available to code that called the function. The Service Tier detects that the XMLPort parameter is ByRef and assumes that you would like to have a return value. For this reason it calls the EXPORT function of the XMLPort automatically and returns the result as an XML formatted string.
Because the return value of an XMLPort parameter is a XML formatted string, the Service Tier uses the schema of the XMLPort to define a complex type in the WSDL. In other words: the output of the XMLPort becomes a type according to the WSDL and can be used as a strong type in Visual Studio.
Let’s have a look at the XMLPort:
and how the function in NAV looks like:
Compare this with Visual Studio.
At the left hand side we see the Web Service ExportData (which is the name that we used to publish the Web Service).
At the upper right hand side the ExportItems function is listed. Notice the ref before the parameter. This is because of the VAR parameter in NAV. The parameter itself is of type NAVItems. In the lower area you can also see the name of the parameter: items. This is the name of the VAR parameter in NAV. Notice that the parameter name starts with lower case, while NAV uses uppercase for the same parameter! This is by design.
The type name of the parameter is NAVItems, which is the name of root element in the XMLPort.
Let’s have a closer look at NAVItems:
The NAVItems type has some basic methods which are inherited from the Object type. But we are interested in the property NAVItem. In the lower area the definition is displayed of this property. This tells us that the property NAVItem is of type NAVItem. This means that it is an array, consisting of zero or more objects of type NAVItem.
Now we are getting closer. Let’s have a look at the type NAVItem:
And now we see the fields that are defined in the XMLPort: No, Description, etc.
Let’s wrap this up:
- The XMLPort parameter becomes a strong type in Visual Studio. The name of the root element is used as type name.
- Each element that has child elements becomes a strong type in Visual Studio. The child elements are added as properties.
- If a child element can occur more than once, then the property becomes an array.
The basis for this behavior is of course the WSDL of the Web Service. The WSDL is used by Visual Studio to generate the proxy with the containing datatypes. The WSDL on its turn is based on the definition of the XMLPort (and the Codeunit of course). There are some properties in the XMLPort that influence the WSDL and thus influence the generated datatypes. In fact you design the schema of the XMLPort using these properties.
MinOccurs and MaxOccurs properties
These two properties specify how many times a certain element can occur. It is very important to set these properties correctly.
The root element must exactly occur one time. This is a basic rule for valid XML. To achieve this, make sure that the MinOccurs and MaxOccurs properties of the root element in the XMLPort are set to Once:
An element of source type Table results in one element per record in the output. Because you don’t know how many records the table contains, the MinOccurs property must be set to Zero and the MaxOccurs property to Unbounded:
Do not try to specify the table element as the root element. This will result in multiple root elements, which is invalid XML. Also, do not forget to set the MinOccurs property of the table element to Zero. By default the MinOccurs property has value Once. But when exporting an empty table (e.g. no records in the filter) the resulting XML does not apply to the MinOccurs rule. This will result in a runtime error of your application.
Set the XMLPort property Format/Evaluate to XML Format/Evaluate. This will cause Visual Studio to know the type of properties, e.g. string, decimal or boolean. By default the Format/Evaluate property is set to “C/SIDE Format/Evaluate”. In that case all properties will be string.
One remark about the Direction property. The default value is Both. When the value is set to Import it is not possible to use the XMLPort as a VAR parameter. That will result in an error ‘The XMLPort ‘Export Items’ is designed for import only.’.
Does this mean that you can also use an XMLPort in a Web Service for importing data? Yes, that is possible! It works both ways.
Until now we did not write any code in NAV. In the next post we will see how to filter the data before exporting it and how to implement paging.