Using XML Web Services to Communicate with Microsoft Axapta

Article
05/08/2007

Bill Thompson
Axapta Developer Support
Microsoft Business Solutions

January 2005

Applies to:
    Microsoft Axapta
    Microsoft Visual Studio® .NET
    Visual Basic® .NET
    ASP.NET

This article assumes that the reader is familiar with Microsoft Axapta, Visual Studio, and ASP.NET. Also, familiarity with the X++ development language (Microsoft Axapta development language) would be beneficial to the reader as some coding in Microsoft Axapta will be required.

Summary: This article describes how to use XML based Web services and the Microsoft Axapta Business Connector to facilitate information transfer between a Web-based application and Microsoft Axapta.

Synopsis
Introduction to Communicating with Microsoft Axapta
Creating the Required Axapta Data Methods
Creating the Web Service
Creating the Web Service Consumer
Conclusion
See Also

Synopsis

This article demonstrates the use of Web services, in conjunction with the Axapta Business Connector, to retrieve information from Microsoft Axapta.

Introduction to Communicating with Microsoft Axapta

This article demonstrates how to use Web services to retrieve basic customer information (name and address information) from Microsoft Axapta. The Web services incorporate the use of the Axapta Business Connector to facilitate information retrieval via the Web service.

Custom X++ code (Axapta’s native development language) will be created, VB .NET code will be used within an ASP.NET Web service to retrieve information from Microsoft Axapta, and an ASP.NET application will be created (using VB .NET) within Visual Studio 2003 to request and display information from the Web service.

Familiarity with Microsoft Axapta and Visual Studio 2003 is assumed in the creation of content for this discussion.

Also, this article assumes that all development and testing is done on the https://localhost/. This means that deployment of the Web service will not be discussed. The See Also links at the end of this discussion provides references to articles that discuss deployment of Web services.

Creating the Required Axapta Data Methods

The initial step in the process is to create methods in Axapta that can be used to return the required information. This will require (for the purposes of this discussion) a class, and a few methods for data return.

Creating the Class

It is a recommended Axapta Best Practice to create projects in Axapta to store custom code, so the first step will be to create a project in Axapta to store the new code:

Click the project icon (immediately left of the yellow question mark “?”) in the toolbar to open the project window.
Right-click on Private (as this is not a multi-developer project),
Choose New and Project from the menus that appear.
Rename the new project by right-clicking and choosing Rename from the menu that appears.
Name the project WebServiceTest, and press the Enter key to save the changes.
Double click on the WebServiceTest project to open the project.

Creating a New Class

Right click on the project name, and choose New | Class in the menu that appears, as shown in Figure 1.

Figure 1. Creating a new class in the WebServiceTest Project

Class1 will now exist in the project.

Double-click on the Class1 project to start the X++ code editor. The following code will be displayed:

class Class1 
{
}

Make the following change to this code:

public class WebServiceCusInfo
{
}

Once the above X++ code has been added, save the modifications by clicking the disk icon in the editor menu bar, and close the editor. Closing the editor ensures that the class has been saved and renamed to WebServiceCusInfo.

Creating the Data Return Methods

The next step is to create the methods that will be used to return the required information.

The first set of information needed will be the customer name. This information is retrieved based on the account number that will be entered into a textbox in the ASP.NET application. This means the methods that are created in Axapta will need to have this account number passed into the method, and the method will return the appropriate information based on this account number. Therefore, the first step will need to be the creation of a new method. To do this, open the WebServiceCusInfo class in the editor by double-clicking on the class name in the project. This is done by:

Open the Project Folder created previously
Locate the WebServiceCusInfo class.
Double Click on the icon to the left of the class name.

Now create the new method in the class. This is done by clicking the first icon in the tool bar of the X++ editor, or by pressing CTRL+N. Modify the new method to look like the following:

public CustName retCustName(AccountNum _acctNum)
{
    ;
    return CustTable::find(_acctNum).Name;
}

By examining the above X++ code, you will see that the method is a public method of type CustName, and that a variable of type AccountNum named _acctNum is passed into the method. The method then calls the CustTable static method find to locate the record that matches the _acctNum value, and returns the Name field value.

Compile and save this method.

The above code demonstrates what needs to be done for the rest of the required information. Following is the code needed to create the rest of the desired methods in this class:

public AddressingStreet retCustStreet(AccountNum _acctNum)
{
    ;
    return CustTable::find(_acctNum).Street;
}


public City retCustCity(AccountNum _acctNum)
{
    ;
    return CustTable::find(_acctNum).City;
}

public stateId retCustState(AccountNum _acctNum)
{
    ;
    return CustTable::find(_acctNum).State;
}

public zipcodeId retCustZip(AccountNum _acctNum)
{
    ;
    return CustTable::find(_acctNum).ZipCode;
}

At this point, this should be all the code needed to display the required information. Once the above has been successfully entered and the code compiles successfully, the next steps are to verify the Business Connector is restarted so the code changes are recognized, and to create the Web service that will be used.

Note: if the code does not compile correctly, please verify the code entered matches the code shown on the previous pages.

Restarting the Axapta Business Connector

To allow the business connector to use the above code, it will have to be restarted. The restart will refresh the code base that the business connector uses:

Open the Axapta Configuration Utility (Start | Programs | Navision Axapta Configuration Utility)
Go to the Business Connector tab. Click on the Shut down button that is found in the Administrative tools section of this tab.
Verify the Computer name is the current machine, and click on the OK button. Then click the Yes button on the confirmation box that appears. At this point, the Business Connector is now shut down.
Click the Register button that is directly above the Shutdown button previously used. Then, choose Register COM+ (Component Services), and verify that the Computer is the current machine. The path to the AxCom.dll should default into the library box.
Press the OK button. This will register the Business Connector.
When completed, a confirmation dialog will be displayed. Click the OK button on the confirmation dialog. Then click the OK button of the Axapta Configuration Utility, and this process is completed.

Creating the Web Service

The next step is to create the Web service that will be used to implement the Axapta Business Connector.

Creating the XML Web Service Project

Visual Studio provides an ASP.NET Web Service project template to help you create XML Web services in Visual Basic and Visual C#.

Creating an ASP.NET Web Service Project

Open Visual Studio 2003 (Start | Programs | Microsoft Visual Studio .NET 2003 | Microsoft Visual Studio .NET 2003) and follow these steps:

On the File menu, point to New, and then click Project.
In the New Project dialog box, select Visual Basic Projects.
Click the ASP.NET Web Service icon.
Enter the address of the Web server on which you will develop the XML Web service and specify WebService1 as the directory name, such as "https://localhost/WebService1". By default, the project uses your local machine, "https://localhost".
Click OK to create the project.

Visual Studio automatically creates the necessary files and includes the needed references to support an XML Web service. When you create an XML Web service project in Visual Studio, you see the Component Designer for Service1.asmx.

Once the project is created, reference the Axapta Business Connector in the project. This is done by the following navigation in Visual Studio:

Project | Add Reference. Choose the COM tab.
The Business Connector will need to be located by finding Axapta COM Connector 1.2 Type Library in the list. Highlight this item, and click the Select button. Once the component is in the Selected Components list, click the OK button.
The next step is to add code to the Web service. If you do not see the code page, double click on the displayed page to get to the edit code page. Now, modify the System.Web.Services.WebService code to match the following:
```
<System.Web.Services.WebService(_
Namespace:="https://AxaptaCustInfo/XmlWebServices", Description:="_
Microsoft Axapta Customer Web services.")> _
Public Class AxaptaWebService
```
Attaching the WebService attribute to a Public class makes it possible for you to include additional information about the XML Web service, such as a namespace for the XML Web service and a description of the XML Web service.

Next create the function needed to access Axapta by adding the following code to the AxaptaWebService class:

<WebMethod(Description:="This method returns the name of the_
 customer number entered. ")> _
 Public Function getCustName(ByVal dAccountNum As String) _
                                   As String
        Dim Axapta As New AxaptaCOMConnector.Axapta
        Dim thisClass As AxaptaCOMConnector.IAxaptaObject
        Dim custName As String
        ' first log into Axapta
        Axapta = New AxaptaCOMConnector.Axapta
        Axapta.Logon("Admin", "", "", "")
        thisClass = Axapta.CreateObject("WebServiceCusInfo")
        Axapta.Refresh()
        custName = thisClass.Call("retCustName", dAccountNum)
        If custName <> "" Then
            Return custName
        Else
            Return "Not Found."
        End If
        Axapta.Logoff()
    End Function

The following is a breakdown of the previous code and a description of what the code is accomplishing:

By declaring the Function getCustName to be a Public function, the function is able to be exposed to the XML Web service.
Dim Axapta As New AxaptaCOMConnector.Axapta line creates a reference in your function to the business connector. Note that this reference is done inside the function. When creating a normal VB .NET application (or C# for that matter) this reference is usually placed under the class declaration. When creating a Web service, this must be done within the function, to keep the reference local to the function.
Dim thisClass As AxaptaCOMConnector.IAxaptaObject creates a reference to a Business Connector Object. Specifically, this will be used to reference the class that was created in Axapta earlier in this discussion. Notice that a string variable is also defined to contain the customer name.
Axapta = New AxaptaCOMConnector.Axapta instantiates our Axapta variable, while Axapta.Logon("Admin", "", "", "") actually opens the connection into the Business Connector.
thisClass = Axapta.CreateObject("WebServiceCusInfo") instantiates the object and allows it to reference the Class that was created in Axapta earlier in this discussion.
Axapta.Refresh() clears the internal memory cache including the cached database information. The method is only used during development to make the object reread the Axapta application code without having to logoff. When the Web service is complete, and ready to be deployed, this line of code can be removed.
custName = thisClass.Call("retCustName", dAccountNum) calls the retCustName method found in the WebServiceCusInfo class (reference via the previously initialized thisClass object), passes in the Account Number via dAccountNum variable, and returns this information to the custName variable.
The lines following this simply test the returned information and sent the appropriate information back out of the Web service.
Axapta.Logoff() closes the connection the Business Connector is using.

Testing the Web Service

After the code is entered as shown above you must test the Web service. This is done by using the Debug menu of Visual Studio. So, either press the F5 key, or choose Debug | Start to start the test.

This is will result in the following screen being displayed:

Figure 2. Testing the web service

Click on the getCustName link. This will result in a description of the function being displayed, along with a Test section.
After the dAccountNum parameter, enter 4000 and press the Invoke button.

The XML Web service responds by returning the converted value in an XML document resembling the following:
```
<?xml version="1.0" encoding="utf-8" ?> 
  <string xmlns="https://LutherCode/XmlWebServices">Light and Design</string> 
```
To stop running the XML Web service and return to the Code Editor, on the Debug menu, click Stop Debugging

Note: For information on debugging Web Services, please see the following article entitled Walkthrough: Creating an XML Web Service Using Visual Basic or Visual C#.

Completing the Web Service Functions

At this point, there are some additional functions that are needed to retrieve the desired information. The code required to complete the Web service:

<WebMethod(Description:="This method returns the street address of_
   the customer number entered. ")> _
        Public Function getCustStreet(ByVal dAccountNum As String) _
                                       As String
        Dim Axapta As New AxaptaCOMConnector.Axapta
        Dim thisClass As AxaptaCOMConnector.IAxaptaObject
        Dim custStreet As String
        ' first log into Axapta
        Axapta = New AxaptaCOMConnector.Axapta
        Axapta.Logon("Admin", "", "", "")
        thisClass = Axapta.CreateObject("WebServiceCusInfo")
        Axapta.Refresh()
        custStreet = thisClass.Call("retCustStreet", dAccountNum)
        If custStreet <> "" Then
            Return custStreet
        Else
            Return "Not Found."
        End If
        Axapta.Logoff()
    End Function

    <WebMethod(Description:="This method returns the city of_
           the customer number entered. ")> _
        Public Function getCustCity(ByVal dAccountNum As String) _
                                       As String
        Dim Axapta As New AxaptaCOMConnector.Axapta
        Dim thisClass As AxaptaCOMConnector.IAxaptaObject
        Dim custCity As String
        ' first log into Axapta
        Axapta = New AxaptaCOMConnector.Axapta
        Axapta.Logon("Admin", "", "", "")
        thisClass = Axapta.CreateObject("WebServiceCusInfo")
        Axapta.Refresh()
        custCity = thisClass.Call("retCustCity", dAccountNum)
        If custCity <> "" Then
            Return custCity
        Else
            Return "Not Found."
        End If
        Axapta.Logoff()
    End Function

    <WebMethod(Description:="This method returns the state of_
      the customer number entered. ")> _
        Public Function getCustState(ByVal dAccountNum As String) _
                                       As String
        Dim Axapta As New AxaptaCOMConnector.Axapta
        Dim thisClass As AxaptaCOMConnector.IAxaptaObject
        Dim custState As String
        ' first log into Axapta
        Axapta = New AxaptaCOMConnector.Axapta
        Axapta.Logon("Admin", "", "", "")
        thisClass = Axapta.CreateObject("WebServiceCusInfo")
        Axapta.Refresh()
        custState = thisClass.Call("retCustState", dAccountNum)
        If custState <> "" Then
            Return custState
        Else
            Return "Not Found."
        End If
        Axapta.Logoff()
    End Function

    <WebMethod(Description:="This method returns the zip code of_
      the customer number entered. ")> _
        Public Function getCustZip(ByVal dAccountNum As String) _
                                       As String
        Dim Axapta As New AxaptaCOMConnector.Axapta
        Dim thisClass As AxaptaCOMConnector.IAxaptaObject
        Dim custZip As String
        ' first log into Axapta
        Axapta = New AxaptaCOMConnector.Axapta
        Axapta.Logon("Admin", "", "", "")
        thisClass = Axapta.CreateObject("WebServiceCusInfo")
        Axapta.Refresh()
        custZip = thisClass.Call("retCustZip", dAccountNum)
        If custZip <> "" Then
            Return custZip
        Else
            Return "Not Found."
        End If
        Axapta.Logoff()
    End Function

After this code has been entered, test the Web service. You will then see the following:

Figure 3. Completed Web Service Test

Creating the Web Service Consumer

The next step is to create an application that will use the Web service.

Creating an ASP.NET Web Application

In Visual Studio 2003, perform the following to create the Web application:

On the File menu, point to New, and then click Project to open the New Project dialog box.
Expand the Visual Basic Projects folder.
Click the ASP.NET Web Application icon. Enter the address of the Web server on which you will develop the Web application and specify WebServiceConsumer as the directory name, such as "https://localhost/WebServiceConsumer". By default, the project uses your local machine, "https://localhost".
Click OK to create the project.
Then on the form, from the Web Forms tab of the Toolbox, drag a Text Box, a Label, and a Button to the design surface of WebForm1.aspx and arrange them to your liking.
Right-click the button you added, Button1, and click Properties on the shortcut menu. In the Properties window, set the Text property to Locate.
Right-click the label you added, Label1, and click Properties on the shortcut menu. In the Properties window, clear the Text property to make this a blank label.

To add a Web reference:

On the Project menu, click Add Web Reference.
In the URL box of the Add Web Reference dialog box, type the URL to obtain the service description of the XML Web service you want to access, such as https://localhost/WebService1/Service1.asmx. Then click the Go button to retrieve information about the XML Web service.
In the Web reference name box, rename the Web reference to AxaptaCustInfo, which is the namespace you will use for this Web reference
Click Add Reference to add a Web reference for the target XML Web service.

Visual Studio downloads the service description and generates a proxy class to interface between your application and the XML Web service.

XML Web Service Discovery

XML Web service discovery is the process by which a client locates an XML Web service and obtains its service description. The process of XML Web service discovery in Visual Studio involves interrogating a Web site following a predetermined algorithm. The goal of the process is to locate the service description.

The service description describes what services are available and how to interact with those services. Without a service description, it is impossible to programmatically interact with an XML Web service

Your application must have a means to communicate with the XML Web service and to locate it at run time. Adding a Web reference to your project for the XML Web service does this by generating a proxy class that interfaces with the XML Web service and provides a local representation of the XML Web service

Accessing the Web Reference

Determine if you can retrieve the desired information. Double click on the Locate button to allow us to enter code. Enter the following code:

Private Sub Button1_Click(ByVal sender As System.Object,_
 ByVal e As System.EventArgs) Handles Button1.Click
        Dim axCust As New AxaptaCustInfo.AxaptaWebService
        Dim custText As String
        
        Try
            custText = axCust.getCustName(TextBox1.Text)
            Label1.Text = custText
        Catch ex As Exception
            Label1.Text = "Not Found."
        End Try
End Sub

Next, examine the code. The Dim axCust As New AxaptaCustInfo.AxaptaWebService line creates an instance of the XML Web service's proxy class.
Then, the Try – Catch expression calls the Web service function getCustName with the value in the textbox, and sets label1 to either display the returned information, or Not Found, depending what is returned.

Now either press F5 or use Debug | Start to test this. Enter 4000 into the text box, and press the Locate button, and see if Light & Design is returned to the Web application.

Note for information on debugging the Web Application, please see Walkthrough: Accessing an XML Web Service Using Visual Basic or Visual C#

Once this is working, add more labels in order to obtain a display like Figure 4:

Figure 4. Final layout

Then, finish off the code of the Locate button so it resembles the following:

Dim axCust As New AxaptaCustInfo.AxaptaWebService
Dim custText, custStr, custCity, custState, custZip As String
Dim custAct As String
custAct = TextBox1.Text
Try
   custText = axCust.getCustName(custAct)
   Label1.Text = custText
Catch ex As Exception
   Label1.Text = "Not Found."
End Try
 
Try
   custStr = axCust.getCustStreet(custAct)
   Label2.Text = custStr
Catch ex As Exception
   Label2.Text = "Unavailable."
End Try
 
Try
   custCity = axCust.getCustCity(custAct)
   Label3.Text = Trim(custCity)
Catch ex As Exception
   Label3.Text = "Unavailable."
End Try
 
Try
   custState = axCust.getCustState(custAct)
   Label4.Text = Trim(custState)
Catch ex As Exception
   Label4.Text = "Unavailable."
End Try
 
Try
   custZip = axCust.getCustZip(custAct)
   Label5.Text = Trim(custZip)
Catch ex As Exception
   Label5.Text = "Unavailable."
End Try

Conclusion

In the preceding description a functional Web service has been created that will integrate with Microsoft Axapta. This is a good base for expanding Web services to include greater interaction with Axapta. Some possibilities include Purchase Order or Sales Order creation, General Ledger integration, Item information, etc.

The next step in this process would be to deploy the Web service and attempt to access the service via a Web server. As stated in the Introduction, this is beyond the scope of this discussion, but the links below will provide information on how to deploy the Web service, and how to configure a Web application to use the deployed Web service.