Bugsy's Blog

Showing NAV Data in SharePoint using Business Data Catalog – Part 2 of 2

2009-04-14T22:21:00Z

This is the second part of the walkthrough, showing how you can show your Dynamics NAV Data in SharePoint. This part will show you how you can use the Web Service and Application Definition File that you created in Part 1, and some examples on how you can integrate the data into a SharePoint Site.

The first part can be found here:

Showing NAV Data in SharePoint using Business Data Catalog – Part 1 of 2

We are now ready to start using the data in SharePoint. Business Data Catalog is a way to generally expose Business Data to SharePoint, and SharePoint can then use it in multiple ways. In this walkthrough I will show the following scenarios:

Using NAV Data in Web Parts
Using NAV Data in SharePoint Lists
Searching for NAV Data

Importing the Application Definition File to SharePoint

The first you need to do is to import the Application Definition File you created in Part 1.

Open up the SharePoint 3.0 Central Administration. There should be a shortcut to this site in your Start Menu. Then select Shared Services Administration for the default Shared Service (called SharedServices1), and click the link called “Import application definition”

Now you specify the .xml file that you just exported from the Business Data Catalog Definition Editor, and click “Import”. You can leave the other options at their default values:

Adding a Business Data List Web Part to a Page

Now it is time to show the NAV Data in one of the BDC Web Parts. Create a New SharePoint Site, or use one of the existing Demo Sites. Please make sure that the Enterprise Site Features in activated for the Site; otherwise you won’t be able to use the BDC Web Parts.

The Site Features can be enabled under “Site Actions->Site Settings->Site Features”

Now, edit the Page, and add a new Web Part of type “Business Data List”

Open the Tool Pane, and specify the Type of the List. You can use the “Browse” button (the small book) to pick the Customer NavLobSystem.

Click OK to close the Tool Pane.

You now have a very wide Web Part with all the columns from your Customer Entity. If you want to remove some of the columns, this can be done from the “Edit View” link. When you are done editing, then click “Exit Edit Mode”, and you are ready to try the Web Part.

You can also try adding a Business Data Item Web Part to the Page, and link the two Web Parts, so the Item shows details for the currently selected Customer in the List.

Using NAV Data in SharePoint Lists

It is also possible to add columns from Business Data to any kind of SharePoint Lists. This can be very useful for e.g. a Document Library.

Create a new Document Library to your Page, and add a couple of Documents. In my example I have created a Document Library with “Customer Letters”

Now, add a new Column to the list, through the “Settings-> Create Column” menu. Give it a Name, and specify that you want to show Business Data. Then specify the Type and which Field to display (e.g. Name).

Click OK, and you now have a new Column in the list that you can use to reference Customer Data in NAV.

Searching for NAV Data

Finally I would like to show how you can use the Business data in the SharePoint Search Feature. This will enable you to search for Business Data the same way you search for any other Data on your SharePoint Site.

To enable SharePoint Search to crawl your Business data, you need to make sure that the Crawler has permissions to the Business Data through the Web Service. In a real deployment you should use a specific account for this, but for my walkthrough, I simply used my own user account.

On the SharePoint 3.0 Central Administration Site, go to “SharedServices1->Search administration-> Default Content Access Account”

Set the Default Content Access Account, and click OK.

Now you need to define a Content Source for the Crawler, so it knows to crawl your Business Data. Go to “SharedServices1->Search administration->Content Sources”, and click “New Content Source”. Specify the Name, Type and Applications for the NavLobSystem as shown here:

Click OK, and you are now ready to start the first Crawl of your data. The current setup does not support Incremental Crawl, so you need to start a Full Crawl.

On the new Content Source click “Start Full Crawl”

When the Crawl is finished, you should check the Log file to see if it was successful. If that is the case, then you are now ready to search for Business Data.

On your Demo SharePoint Site, try searching for “Barcelona”. You should now get one hit from the NAV Demo Data: Customer 34010100 - Libros S.A.

Final Thoughts

This walkthrough became a little longer than I planned, but I hope it shows what steps is needed to show Dynamics NAV data in SharePoint, using the Business Data Catalog. There are many steps, but they are pretty easy as soon as you have tried them.

I think this way of enabling Business Data for SharePoint is a very good way, because it allows you to integrate the data very tightly with SharePoint, in central features like Search and Lists.

Thanks
/Bugsy

Showing NAV Data in SharePoint using Business Data Catalog – Part 1 of 2

2009-04-14T17:52:00Z

At the conference Directions EMEA 2009, I did a session on Dynamics NAV and SharePoint. In that session I showed a short demo on how you can show Dynamics NAV data in SharePoint, using the Business Data Catalog feature. You can see more about the conference at http://www.directionsemea.com

Here I would like to walk through the steps to do the demo, so you can try this out as well. I think it is a quite simple way to enable SharePoint users to access the data that is in your Dynamics NAV system.

This first part of the walkthrough will show how you build the Web Service and Application Definition File for SharePoint. The second part will show how you can then use this in SharePoint.

Step 1: Creating the NAV 2009 Web Service

The first step is to create a NAV 2009 Web Service to expose the data that you want. In our example we will expose Customer Data.

Creating a Web Service in NAV 2009 is really simple. In the Classic Client, open the Web Service Form. It is found under “IT Administration->General Setup->Web Services”

In the Web Services Form, you add a line with Page 21, call the Service “Customer” and set a checkmark in the Published Column. This will create a Web Service, exposing all the Fields on Page 21 “Customer Card”. If you want to expose other fields, you can create a specific Page for that, but for my example I have just used the standard Customer Card Page

Before you can try the new Web Service, you need to make sure that the “Microsoft Dynamics NAV Business Web Services” service is started on the machine. In a default installation this service is not started automatically, so you might want to set the Startup Type to Automatic as well.

Now you can actually try out your new Web Service. The default URL for the Web Service is:

http://localhost:7047/DynamicsNAV/WS/CRONUS_International_Ltd/Page/Customer

If you want to know more about NAV 2009 Web Services, then you can try out some of the Web Services Walkthroughs in the C/SIDE Reference Guide Online Documentation.

Step 2: Creating a new BDC compatible Web Service

The Web Service that you have just created does unfortunately not have the right format for the SharePoint Business Data Catalog, so you need to create a new Web Service that Business Data Catalog understands, and then from that call the NAV 2009 Web Service.

In Visual Studio (I used VS 2005), create a new ASP.NET Web Service Application, called NavBdcWebService

Rename the Service1.asmx file to NavBdcWebService.asmx, and call the Web Service class for NavBdcWebService. Also remember to update the reference in the .asmx file to the new name of the class. To edit that file, right click the NavBdcWebService.asmx file in the Solution Explorer and select “View Markup”

<%@ WebService Language="C#" CodeBehind="NavBdcWebService.asmx.cs" Class="NavBdcWebService.NavBdcWebService" %>

In order to access the NAV 2009 Web Service from your new Web Service, you need to add a Web Reference to the NAV 2009 Web Service.

In the menu, select “Project->Add Web Reference…” and specify the URL for the NAV 2009 Web Service called Customer:

http://localhost:7047/DynamicsNAV/WS/CRONUS_International_Ltd/Page/Customer

Give the Web Reference the name “NavCustomer” to avoid conflicts with the Customer Class there, and click “Add Refernce”:

Now replace all the code in NavBdcWebService.asmx.cs file with the following:

using System;
using System.Data;
using System.Web;
using System.Collections;
using System.Web.Services;
using System.Web.Services.Protocols;
using System.ComponentModel;
using System.Collections.Generic;
using NavBdcWebService.NavCustomer;

namespace NavBdcWebService
{
    /// <summary>
    /// MOSS BDC Compatible Webservice for getting NAV Data
    /// </summary>
    [WebService(Namespace = http://tempuri.org/)]
    [WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)]
    [ToolboxItem(false)]
    public class NavBdcWebService : System.Web.Services.WebService
    {
        /// <summary>
        /// Finder method for finding Customers
        /// </summary>
        /// <param name="no">Filter parameter for the Customer No.</param>
        /// <param name="name">Filter parameter for the Customer Name</param>
        /// <param name="noOfRecordsToReturn">Number of Customers to return</param>
        /// <returns>Array of Customer objects, with all the fields on a Customer</returns>
        [WebMethod]
        public Customer[] CustomerFinder(string no, string name, int noOfRecordsToReturn)
        {
            Customer_Service service = new Customer_Service();
            service.UseDefaultCredentials = true;
            service.Url = http://localhost:7047/DynamicsNAV/WS/CRONUS_International_Ltd/Page/Customer;

            List<Customer_Filter> filters = new List<Customer_Filter>();

            if (!string.IsNullOrEmpty(no))
            {
                Customer_Filter filter = new Customer_Filter();
                filter.Field = Customer_Fields.No;
                filter.Criteria = no;
                filters.Add(filter);
            }

            if (!string.IsNullOrEmpty(name))
            {
                Customer_Filter filter = new Customer_Filter();
                filter.Field = Customer_Fields.Name;
                filter.Criteria = name;
                filters.Add(filter);
            }

            return service.ReadMultiple(filters.ToArray(), null, noOfRecordsToReturn);
        }
    }
}

The code simply adds a Web Method called CustomerFinder. This is the Method that Business Data Catalog will use to get data.

The Method takes two Filter Parameters “no” and “name”. For this example I have chosen only to enable filtering on those two fields, but you can add other fields as well. Business Data Catalog supports up to a total of 30 parameters to the Finder Method.

The third parameter called “noOfRecordsToReturn” is used by Business Data Catalog to limit the number of records to look for within the filter. This protects your service from excessive unfiltered requests from the SharePoint users.

The Method simply adds the two filters to a Filter List, and calls the ReadMultiple Method on the NAV 2009 Web Service, passing the Filter List and the noOfRecordsToReturn parameter.

The Method returns an array of Customer Objects as defined by the NAV 2009 Web Service.

The new Web Service is now done, and you should try it. Simply run the web service from Visual Studio, and invoke the CustomerFinder Method with the parameters no=10000 and noOfRecordsToReturn=1

You should now get an XML document with the Customer data for the Customer 10000 – “The Cannon Group PLC”

You can now deploy the new web service, but for the walkthrough we will just stay with the Service running on the ASP.NET Development Server in Visual Studio. Just make sure that the Web Service is running in Visual Studio. The name of the new Web Service will then be (Your port number might be different):

http://localhost:55241/NavBdcWebService.asmx

Step 3: Creating the BDC Application Definition File

In order to tell BDC (Business Data Catalog) how the Customer Entity is structured, we need to create an Application Definition File. This is an XML file, but creating it manually is not trivial, so we will use the Business Data Catalog Definition Editor that come as part of the SharePoint Server 2007 SDK:

http://www.microsoft.com/downloads/details.aspx?familyid=6d94e307-67d9-41ac-b2d6-0074d6286fa9&displaylang=en

In the Business Data Catalog Definition Editor, Add a new LOB System. We want to connect to a Web Service, so specify the URL for the NavBdcWebService that you just created:

Click Connect, and drag the CustomerFinder Method into the Design Surface

Click OK, and name the System NavLobSystem.

The Business Data Catalog Definition editor has now imported the information from the Web Service, but unfortunately there are a number of manual steps that you need to do to set this up properly. When you have done this for this Entity (Customer) it is pretty easy to do the same for an additional Entity.

Set the Version of NavLobSystem to “1.0.0.0” and WildcardCharacter to “*”

Also rename the Entity to be called “Customer”.

Adding an Identifier for the Customer

In order to identify an Entity in the Business Data Catalog, you need to add an Identifier. Call the Identifier “No”, and leave the default datatype to System.String:

Defining Filters for the CustomerFinder Method

We have already imported most of the data for the CustomerFinder Method, but we need to define the Filters for the two filter parameters No and Name. Create both of them as WildcardFilter

In order to limit the number of records to search for, you should also create a Filter called Limit of type “Limit”:

Defining Parameters for the CustomerFinder Method

We also need to do a little extra work on the parameters of the CustomerFinder Method

For the parameter called “no”, set FilterDescriptor to the Filter we just created called “No” and Identifier to the identifier we just created: “No[Customer]”
For the parameter called “name”, set FilterDescriptor to “Name” and leave the Identifier blank
For the parameter called noOfRecordsToReturn, set the FilterDescription to “Limit” and leave the Identifier blank.
For the “No” field of the returned Item (CustomerFinder->Parameters->Return->Return->Item->No), also set the Identifier to “No[Customer]”

Defining the Method Instances

In order for the BDC to call the Finder Method, we need to define a number of different Method Instances.

An Enumerator
A Finder
A Specific Finder

The first one is of type idEnumerator. It can return all the Identifiers for the Customers. Call this Method Instance “GetCustomerIDs”

You can actually try this Method Instance in the Business Data Catalog Definition Editor. Simply click “Execute” and “Next” on the form that opens. You should now get a list of Customer IDs:

The second Method Instance is of type SpecificFinder, and it can find an Entity for a specific Identifier. Call this Method Instance “FindCustomer”

The last Method Instance is of type Finder, and it is used to return multiple Entities. Call this Method Instance “FindCustomers”

You can also test the two other Method Instances directly in the Business Data Catalog Definition Editor. Click Execute on each of them to validate that they work as expected.

FindCustomer should return a single Customer when specifying a Customer No
FindCustomers should return a list of Customers within the filter specified

Note: The result page has a lot of fields, so it is difficult to see exactly which Customers is returned. You can expand some of the columns to see more of the content.

Adding Display Names for the Parameters and returned Fields

By default the display name will be the same as the field name. For some of the fields, this is not nice, because it contains underscores instead of spaces. You can specify a different Display name for each of those, so it looks nicer for the user.

Export the Application Definition File to an XML file

Finally you export the Application Definition File to an XML file that can later be imported into SharePoint Business Data Catalog.

If you later make changes to the Definition File, then remember to increment the Version Number. This will allow BDC to update existing definitions.

To be continued…

This completes the first part of this walkthrough. The second part will show you how you can then use the Web Service and Application Definition File in SharePoint.

Thanks
/Bugsy

Welcome to Bugsy's Blog

2009-04-06T03:35:00Z

My name is Peter Christensen, and I am Development Manager for the Microsoft Dynamics NAV Client Team. I have worked for Navision and later Microsoft for many years, and I have always been focused on creating a great user experience for the users of our system.

My nickname at work is "Bugsy", so therefore I decided to call this blog "Bugsy's Blog". The story behind the nickname is a little long, so I will save you for the details - but I can assure you that it does not have anything to do with Bugs or Code Defects in our product...

Besides being passionate about NAV and Microsoft in general, I also likes working with Developer Processes and Practices, so I might make some Posts on that as well.

It is important to note: The views expressed in this blog are my individual views and do not necessarily represent those of Microsoft. This information is provided by way of general information only and should not be relied on without obtaining independent expert advice. These postings are provided "AS IS" with no warranties and confer no rights. You assume all risk for your use.

/Bugsy