Learning to fish
Give a man a fish and you feed him for a day; teach him to use the Internet, and he won’t bother you for weeks!
This is going to be a real challenge for the one that wants to play with the new technology that Web services enablement brings, but is a little unsure where to start. A good number of people that are experienced NAV consultants and C/AL developers are going to need to learn some new technologies if they want to start experimenting with the new extensibility options in Dynamics NAV 2009, or even simply understand what options are available for their new solution designs or sales presentations. This article is going to be all about practical examples—real sample applications that you can create for yourself. Some of these examples start off with one set of requirements that evolve as we progress through the design process. The examples are deliberately kept this way to help you to understand that the path to your final working solution is not always the shortest. Sometimes you get an idea for an application and as you proceed with the design, you think of things that would be better or easier to use. Sometimes your initial design simply won’t work when you start to try it out. It’s important to realize that designs are not precious and it’s OK to change your mind. There are a couple of important issues to consider: always ensure you are solving the business problem, and don’t get carried away gold-plating your design. Keep it simple, and once it is working and meets the initial requirements, you can then go back and add the bells and whistles (but you’d better check with whoever is paying the bills first).
If you aren’t a .NET programmer, and you have never created a web site or Web service in your life, this article is not a place to tell you the best way to do these things, but instead is a place to show you that with a very limited knowledge of .NET, a web browser to do some research, and enough time, you can create pretty much anything you can imagine.
First of all, let’s get some theory out of the way so that we have a basic understanding of what we’re dealing with.
What’s a Web service?
Web services have been around for a few years now but they are new to NAV (well, sort of— but more on that later). A good way to distinguish between technical and non-technical NAV consultants is to ask them if NAV supports Web services and watch to see if their eyes glaze over. There’s no wonder some NAV consultants struggle to understand Web services as a concept; if you’re not a developer and you have never worked with Web services, learning the basics might be more than a little bit scary. Here’s a typical definition you might find on the Web; don’t be put off by the geek-speak.
A scary geeky definition of a Web service
A ‘Web service’ (also Web Service) is defined by the W3C as ‘a software system designed to support interoperable machine-to-machine interaction over a network’. Web services are frequently just Web APIs that can be accessed over a network, such as the Internet, and executed on a remote system hosting the requested services.
There are a lot of acronyms and jargon phrases to learn if you want to talk the talk, but let’s take a look at what a Web service is in simple terms.
To start with, let’s consider a comparison between web sites, something we are all familiar with, and Web services.
One might like to think that a Web service is to a computer what a web site is to a person. If you want to know what’s on TV tonight, you can type the URL for a TV Listings site into a web browser and bring up a page with details. It’s not going to take you long to find the required information, but what if you wanted to write a computer program to send an e-mail when your favorite TV show was about to start, how would you go about that? This is a more complex problem, we know the data is there on the web site, freely available to all humans, but we can’t just tell our computer to go off and read the web site (well we can—but deciphering it may require a fair amount of clever programming). Wouldn’t it be great if there was a computer-friendly version of the data on the web site that allowed computers to ask for information and get answers back? Wouldn’t it be great if you could write your program to make the call to this service without the need to install any special software components on your computer? Yes, it is great, and that’s why Web services came into being and have now become so popular.
It’s not just for the Web
It’s not immediately obvious why we would want to expose our precious company data that we keep locked up in our ERP system on the Web, but just because they’re called Web services doesn’t mean they’re just for the World Wide Web. Let’s consider the intranet compared to the internet. It didn’t take long for companies to realize that the popularity of internet sites and the ease of use that everyone was experiencing through the world wide web could provide great benefits within the boundaries of a company’s safe internal network—a kind of mini-internal-internet or intranet. For Dynamics NAV, the analogy between Web Sites and Web services works even better when we consider an intranet. What if different departments could pull data directly from the ERP system and use it in their own specialist applications? This is where the real value of Web services enablement in Dynamics NAV 2009 comes into its own. It is now possible to take any functionality from within the ERP solution and expose it to other applications as Web services; it’s not just possible, it’s dead easy!
What can we do with them?
OK, so it’s easy to expose NAV functionality, so what? Well if you can call any Codeunit or Page from within NAV with pretty much any software package that you can extend, there are limitless possibilities to create fantastic productivity applications for the business. Here are just a few examples:
- Let staff submit their expenses from Excel, or from their mobile phone, without needing to re-key them into the finance system.
- Allow users to create new customer accounts from within Word or from an intranet web page.
- Provide a Vista Sidebar gadget that shows the number of documents requiring approval and allows the user to approve the document without needing to open the ERP.
- Provide a simple single-task Windows application that will let staff see where stock is.
These examples are just a few that spring immediately to mind, but if you have the know-how, you can do pretty much anything. So how easy is it to expose NAV functionality as a Web service? Let’s find out.
Calling a NAV Web service
There is a great series of articles on MSDN by Manuel Oliveira that explain how to expose NAV functionality as a Web service. If you have never read these, you may want to skim through them after reading this example to see just how easy we have it with the new version of NAV.
Talking with NAV—the hard way!
Visit http://msdn.microsoft.com/en-us/library/ms952182.aspx and http://msdn.microsoft.com/en-us/library/ms952079.aspx for a couple of examples that explain the multiple hoops we needed to jump through in order to access NAV functionality using Web services. That’s before NAV 2009 came along!
Since these early examples of NAV extensibility, the Windows Communication Framework has made things easier, and Kris Rafnsson has provided a blog posting and sample application that allows you to call NAV functionality as a Web service without using message queues. This example is pretty amazing, but there is still a fair amount of work required to get this up and running and build new solutions. Although this is a big improvement on the Message Queue approach, it is nothing compared to the simplicity and elegance of the NAV 2009 Web services enablement. You can read through Kris’s post at http://blogs.msdn.com/nav/archive/2008/04/15/using-web-services-toaccess-microsoft-dynamics-nav-5-0.aspx.
In Manuel’s first example (although not actually a Web service), he creates a simple NAV function that will accept a text string and return the text string back but converted to upper case. This example spans 15 printed pages and uses a lot of geeky stuff. As a bare minimum, we are going to need a Codeunit to expose and a .NET program to call the thing, so let’s forget about these and just compare the components that are needed to take care of the plumbing:
- Microsoft Message Queue
- Navision Communication Component
- XMLDOM automation control
- Navision Application Server
- A lot of complicated C/AL code using InStreams and OutStreams and XML manipulation
Manuel’s examples were written in 2004 and, although they’re very well written, the whole thing is just too hard! After reading the articles, you’ll understand why there hasn’t been a glut of NAV components on the market using Web services exposed by NAV. Our example by contrast requires the following (again ignoring the Codeunit we are exposing and the .NET program needed to call it):
- Dynamics NAV 2009 Business Web services
- A new record in a table with a check in a box
Creating a Web service
Let’s start by creating our very simple Codeunit. In this example, I have created Codeunit 50001 called NAV Codeunit, which has a single function called ConvertStrToUpperCase that takes a 50 character text field and returns a 50 character text field that has been converted to upper case.
It wasn’t absolutely necessary for this example, but I put some code in the OnRun() trigger of the Codeunit that will demonstrate the Codeunit working when run. Here is the output from running the Codeunit in NAV:
Now we can expose this Codeunit as a Web service. In the Classic client, select Administration | IT Administration | General Setup | Web Services.
This is just a regular NAV form, so fill in the details on a new record with Object Type as Codeunit, Object ID as 50001, and Service Name as NAV Codeunit. To publish the Web service, tick the Published field. I just happened to give the Web service the same name as the Codeunit, but this is not necessary, you can call it whatever you like.
We have now exposed NAV functionality as a Web service—how easy was that?
Calling the Web service
The .NET program to call the Web service is going to be a little harder. We’re going to create a simple C# console application using Microsoft Visual Studio 2008 Professional Edition. (This is installed on the Marketing Beta release of the product which all partners can download from PartnerSource.)
Create a new Console Application, let’s call this one SayHelloToNAV2009.
The project gets created with a Program.cs file with enough code generated for you to allow the project to compile and run. There’s no way I can teach you to program in C# in this article, there are whole books dedicated to the subject; instead what I’ll do is give you the details you need to be able to recreate our examples for yourself. If you like what you see, maybe you’ll go on to do some more .NET programming and your next book will be one on C#. The great thing about .NET languages and Visual Studio is there’s a huge amount of knowledge freely available on the Web.
The first thing we need to do is add our Web service to the project. To do this, right-click on the References node in the Solution Explorer window and select Add Service Reference.
Visual Studio 2005 is different
These instructions are for adding a web reference using Visual Studio 2008. In 2005, things work a little differently. Instead of selecting References | Add Service Reference | Advanced | Add Web Reference, you simply selected Add Reference | Add Web Reference.
In the dialog that is displayed, click the Advanced button, and then click the Add Web Reference button.
In the Add Web Reference dialog form, enter http://nav-srv-01:7047/DynamicsNAV/ws/CRONUS_International_Ltd/Services as the URL for the Web service. This will display the group of Web services that are exposed by NAV.
Where do I find that URL?
The format of the URL is quite straightforward. Let’s break it up into chunks.