Web services are an industry standard software interface that allows software applications to interoperate using standard interface specifications along with standard communications services and protocols. When NAV publishes some web services, these functions can be accessed and utilized by properly programmed software residing anywhere on the Web. This software does not need to be directly compatible with C/SIDE or even .NET; it just needs to obey web services conventions and have security access to the NAV Web Services.
Some benefits of NAV Web Services are:
- Very simple to publish (that is, to expose a web service to a consuming program outside of NAV)
- Provides managed access to NAV data while respecting and enforcing NAV rules, logic, and design that already exists
- Uses Windows Authentication and respects NAV data constraints
- Supports SSL—Secure Socket Layer
- Supports both the SOAP interface (cannot access Query objects) and the OData interface (cannot access Codeunit objects)
Disadvantages of NAV Web Services include:
- Allowing access to a system from the Web requires a much higher level of security
- The NAV objects that are published generally need to be designed (or at least customized) to properly interface with this very different user interface
- Access from the Web complicates the system administrator's job of managing loads on the system
There are several factors that should be considered in judging the appropriateness of an application being considered for web services integration. Some of these are:
- What is the degree to which the functionality of the standard RTC interface is needed? A web services application should not try to replicate what would normally be done with a full client, but should be used for limited, focused functionality.
- What is the amount of data to be exchanged? Generally, web services are used remotely. Even if it is used locally, there are additional levels of security handshaking and inter-system communications required. These involve additional processing overhead. Web services should be used for low data volume applications.
- How public is the user set? For security reasons, the user set for direct connection to our NAV system should generally be limited to known users, not the general public. Web services should not be used to provide Internet exposure to the customer's NAV system, but rather for intranet access.
Because web services are intended for use by low-intensity users, there are separate license options available with lower costs per user than the full client license. This can make the cost of providing web services-based access quite reasonable, especially if by doing so, we increase the ability of our customer to provide a better service to their customers and to realize increased profits.
Three types of NAV objects can be published as Web Services: Pages, Queries, and Codeunits. The essential purposes are:
- Pages provide access to the associated primary table. Use Card Pages for table access unless there is a specific reason for using another page type.
- Codeunits provide access to the functions contained within each Codeunit.
- Queries provide rapid, efficient access to data in a format that is especially compatible with a variety of other Microsoft products as well as products from other vendors.
An XMLPort can be exposed indirectly as a Codeunit parameter. This provides a very structured way of exposing NAV data through a Web Service. (See AJ Kauffmann's blog series on XMLPorts in Web Services at http://kauffmann.nl/index.php/2011/01/15/how-to-use-xmlports-in-web-services-1/). There is an example later in this chapter.
When a Page has no special constraints, either via properties or permissions, there will normally be eleven methods available. They are:
Create: Create a single record (similar to a NAV INSERT).CreateMultiple: Create a set of records (passed argument must be an array).Read: Read a single record (similar to a NAV GET).ReadMultiple: Read a filtered set of records, paged. Page size is a parameter.Update: Update a single record (similar to a NAV MODIFY).UpdateMultiple: Update a set of records (passed argument must be an array).Delete: Delete a single record.IsUpdated: Check if the record has been updated since it was read.ReadBiyRecID: Read a record based on the record ID.GetReciIDFromKey: Get a record ID based on the record key.Delete_<PagePartName> (PagePartRecordKey): Delete a single record that is exposed by a page part of TypePagesuch as the Sales Order Subform Page Part of the Sales Order page.
Whatever constraints have been set in the page that we have published will be inherited by the associated web services. For example, if we publish a page that has the Editable property set to No, then only the Read, ReadMultiple, and IsUpdated methods will be available as web services. The other five methods will have been suppressed by virtue of the Editable = No property.
A codeunit that has been published as a web service has its functions made available to for access. A query published as a web service provides access to a service metadata (EDMX) document or an AtomPub Document. To learn more about using queries published as web services, refer to the information published in the Developer and IT Pro Help in the system or in MSDN.
Publishing a web service is one of the easiest things we will ever do in NAV. But, as stated earlier, that doesn't mean we will be able to simply publish existing objects without creating versions specifically tailored for use with Web Services. However, for the moment, let's just go through the basic publishing process.
The point of access is the Departments menu through Navigation Pane | Departments | Administration | IT Administration | General | Web Services. The Web Services page displays as shown in the following screenshot.
The first column allows us to specify whether the object is a Page, Codeunit, or Query. That is followed by the Object ID and then the Service Name. Finally, the Published flag must be checked. At that point, the web services for that object have been published.
Prior to using web services, we must enable them from the NAV Administration application. In NAV Administration, we can see the checkboxes for enabling. We can enable either SOAP Services, OData Services, or both, as shown in the following screenshot:
Once an object has been published, we may want to see exactly what is available as a web service. Since web services are intended to be accessed from the Web, in the address bar of our browser, we will enter the following (all as one string):
http://<Server>:<WebServicePort>/<ServerInstance>/WS/ <CompanyName>/services
Example URL addresses are:
http://localhost:7047/DynamicsNAV/WS/Services http://Arthur:7047/DynamicsNAV/WS/CRONUS International Ltd/Services
When the correct address string is entered, our browser will display a screen similar to the following image. This image is in an XML format of a data structure called WSDL, Web Services Description Language:
In this case, we can see that we have two NAV SOAP Services available: Codeunit/Radio_Show_Management and Page/Radio_Show_Card.
To see the methods (that is, NAV functions) that have been exposed as web services by publishing these two objects, we can enter other similar URLs in our browser address bar. To see the web services exposed by our codeunit, we change the URL used earlier to replace the word Services with Codeunit/Radio_Show_Management. We must also include the company name in the URL that lists the methods WSDL.
To see the OData services, change the URL to the following form:
http://<Server>:<WebServicePort>/<ServerInstance>/OData
From that entry in our browser, we get information about what's available as OData. OData is structured like XML, but it provides the full metadata (structural definition) of the associated data in the same file as the data. This allows OData to be consumed without the requirement of a lot of back and forth technical pre-planning communications.
The actual consumption (meaning "use of") of a web service is also fairly simple, but that process occurs outside of NAV in any of a wide variety of off-the-shelf or custom applications, not part of this book's focus. Examples are readily available in Help, the MSDN library, the NAV forums, and elsewhere.
Tools that can be used to consume NAV Web Services include, among others, Microsoft InfoPath, Microsoft Excel, Microsoft Sharepoint, applications written in C#, other .NET languages, open source PHP, and a myriad of other application development tools. Remember, web services are a standard interface for dissimilar systems.
As with any other enhancement to the system functionality, serious thought needs to be given to the design of what data is to be exchanged and what functions within NAV 2015 should be invoked for the application to work properly. In many cases, we will want to provide some simple routines to perform standard NAV processing or validation tasks without exposing the full complexity of NAV internals as web services.
Perhaps we want to provide just two or three functions from a Codeunit that contains many additional functions. Or we want to expose a function that is contained within a Report object. In each of these instances and others, it will be necessary to create a basic library of C/AL functions, perhaps in a codeunit that can be published as web services (generally recognized as a best practice).
Note
Use of web services carries with it issues that must be dealt with in any production environment. In addition to delivering the required application functionality, there are security, access, and communications issues that need to be addressed. It is recommended that a NAV Web Service not be directly exposed to external users, but NAV data be secured by limiting access through the use of custom, functionally limited, external software interfaces. While beyond the scope of this text, proper attention to data security is critical to the implementation of a good quality solution.
WDTU subscribes to a service that compiles listenership data. That data is provided to subscribers in the form of XML files. The agency that provides the service has agreed to push that XML data directly to a web service exposed by our NAV 2015 system. This approach will allow WDTU to have access to the latest listenership data as soon as it is released by the agency.
WDTU must provide access to the XMLport that fits the incoming XML file format. The handshaking response expected by the agency computer from our web service is a fixed XML file with one element (Station ID) and an attribute of the said element (Frequency).
The first step is to build our XMLport. We access the XMLport designer through Object Designer | XMLport button | New button. Define the new XMLport lines as shown in the following screenshot:
After we have the lines entered, we will click on Alt + F | Save As…. Fill in the Save As screen, as shown in the next image, and click OK to save and compile the XMLport without exiting the XMLport Designer:
Highlight the blank line at the bottom of the XMLport Designer screen and click Shift + F4 (or the Properties icon, or right-click then click Properties) to display the XMLport properties screen.
Set the Format/Evaluate property to XML Format/Evaluate. This allows Visual Studio to automatically understand the data types (integer, decimal, and so on) involved. Set UseDefaultNamespace to Yes, and DefaultNamespace to urn:Microsoft‑dynamics‑nav/xmlports/x50000 (which is the default format) or urn:Microsoft‑dynamics‑nav/xmlports/RatingsImport.
Even though we are using the XMLport as an import only object, make sure the Direction property stays at <Both>. When the value is set to either Import or Export, it is not possible to use the XMLport as a Var (by reference) parameter in the codeunit function which we will expose as a web service.
Following is the XMLport 50000 Properties screen with these changes in place:
After we close the Properties screen for the XMLport, we can highlight the Root Element line and display its properties. Set the property MaxOccurs to Once, as shown in the following image:
Close Root Properties, highlight RatingsData Table Element, and access its Properties screen. Set MinOccurs to Zero and make sure MaxOccurs remains at the default value of <Unbounded> as shown in the following screenshot. Once this is done, close the RatingsData – Properties screen. Because our XMLport matches the incoming data format from the listenership ratings agency, no C/AL code is necessary in this XMLport. Exit XMLport Designer and save and compile XMLport 50000.
Now that we have our XMLport constructed, it's time to build the codeunit that will be published as a web service. Go to the Object Designer | Codeunit button | New button. Then click on the menu option View | C/AL Globals | Functions tab. Enter the new Function name of ImportRatings and click on the Locals button.
In the C/AL Locals screen, enter the single parameter RatingsXML, Type XMLport, and a SubType of Ratings Import. Make sure the Var column on the left is checked. The C/AL Locals screen should then look like the following screenshot:
Now click on the Return Value tab and set Return Type to Text and Length to 250. Exit the C/AL Locals and C/AL Globals screens, returning to the Codeunit C/AL Editor screen. Finally, we will highlight our new Function in the Functions tab, and set the Local property to No
so that we can access this function from Web Services.
Before proceeding any further, let's save our work. Just as in XMLport Designer, we can save our work without exiting the Designer by clicking on File | Save As… , then entering the designer object number (50001) and name (Ratings Webservice).
We only need two lines of C/AL code in the codeunit. The first line's task is to import the XML utilizing the XMLport parameter to cause the XMLport to process. The second line of code's purpose is to send the required text response back to the external system, with the response formatted as XML data. That code looks like the following image in C/AL Editor:
Exit Codeunit 50001, compile and save it. Now we want to publish the codeunit that we have just created.
Open the Role Tailored Client, navigate to Departments/Administration/IT Administration/General/Web Services (or just search for Web Services using the Search box) and invoke the Web Services page. Fill in Object Type of Codeunit, Object ID of 50001, Service Name of WDTU Ratings, and check Published.
Now, to test what we've done, we need to open a browser and enter a URL in the following format:
http://<Server>:<SOAPWebServicePort>/<ServerInstance>/WS/<CompanyName>/services
For example, more specifically:
http://localhost:7047/DynamicsNAV70/WS/CRONUS International Ltd/Codeunit/WDTU_Ratings
Or, for testing purposes, we could just click on the Web icon on the right hand end of our new entry in the web services screen (as shown in the preceding image). The result in our browser screen should look like the following screenshot, showing that we can connect with our web service and that our XMLport contains all the fields for the data that we plan to import:
