Using Axapta Business Connector to Create Microsoft Axapta Ledger Journals

 

Bill Thompson, Axapta Developer Support
Microsoft Business Solutions

February 2006

Applies to:
   Microsoft® Business Solutions–Axapta® 3.0, now part of Microsoft Dynamics™
   Microsoft Visual Studio® 2005
   Microsoft Visual Basic® 2005

Summary: Find out how to use Microsoft Axapta Business Connector, custom Microsoft Axapta X++ code, and Visual Basic 2005 to create and post ledger journals within Microsoft Axapta 3.0. The ledger journal entry will consist of one journal line.

Contents

Introduction
Determining Required Axapta Methods
Axapta Modifications
Visual Basic 2005 Application
Where to Go from Here
Conclusion

Introduction

Learn how to use Visual Basic 2005 to develop a Windows-based application in Visual Studio 2005 that will create and post ledger journal entries within Microsoft Axapta. You will see that, because of the way this application is created, the transferring of Windows application logic to a Web-based application is likely to be an uncomplicated exercise.

Readers should be familiar with Microsoft Axapta, Visual Studio 2005, and Visual Basic 2005.

When you complete all the steps described in this paper, your finished application should resemble the Create Ledger Journal screen shot shown in the figure below.

Figure 1. Finished Windows application

Note that the Business Connector has access to virtually all business logic that exists within Axapta. This allows the developer to just create "wrapper" code for the business logic stored in the object. The wrapper code then is used to pass data between the application and Axapta, and to start the desired processes.

Determining Required Axapta Methods

The first step in the project is to determine which Axapta objects are needed to perform the required operations. By examining Axapta processes, we can determine that the tables LedgerJournalName, LedgerJournalTable, and LedgerJournalTrans are to be used, and that the classes LedgerJournalCheckPost and NumberSeq will be needed.

  • LedgerJournalName will contain the name of the journal.
  • LedgerJournalTable and LedgerJournalTrans tables will be the header and lines tables, respectively.
  • NumberSeq class will be used to get the number sequence value for the journal number.
  • LedgerJournalCheckPost class will be used to validate the ledger entries and to post them, if the entries are valid.

Axapta Modifications

Multiple ways are available for processing the information for this project. For example, Axapta objects can be referenced within Visual Basic 2005, and processed within the application. Another method is to create all the logic to do the processing within Axapta, and pass the required information from the external application into Axapta, and then call the Axapta processes. For the purpose of this discussion, and for code reusability, the second method will be used. This way, the Button.Click Event of the Windows application can easily be mapped to a Web application Button.Click Event. This is also the reason the connection to Axapta, through the Business Connector, is applied to the Button.Click Event.

Create the Project

It is a recommended Axapta Best Practice to create projects in Axapta to store custom code, so the first step is to create a project in Axapta to store the new code. Click the project icon in the toolbar to open the project window. Next, right-click Private (because this is not a multi-developer project), and then click New and Project from the menus that appear.

Rename the new project by right-clicking the project name and choosing Rename from the menu that appears. Name the project AxLedgerDemo, and press ENTER to save the changes.

Now, double-click AxLedgerDemo to open the project.

Create the Class

Right-click AxLedgerDemo (the project name), click New, and then click Class from the menu that appears. Class1 (or something similarly named) should now appear within the project. To change the name to something more meaningful, enter the X++ code editor by double-clicking the Class1 (or similarly named class) object. Modify the code to match the following example:

class AxLedgerDemo
{
  LedgerJournalName      ledgerJournalName;
  LedgerJournalTable     ledgerJournalTable;
  LedgerJournalTrans     ledgerJournalTrans;
  LedgerJournalCheckPost   ledgerJournalCheckPost;
  NumberSeq          numberSeq;

  LedgerJournalType      journalType;
}

After you have finished modifying the code, save it by clicking the disk icon in the editor. Then, close the editor. This ensures that the code modifications have been saved, and that the class has been renamed to AxLedgerDemo.

An examination of the previous code shows that this class has declared objects that are global in scope (able to be referenced by class methods). All objects except the journalType variable were mentioned previously in this discussion. The journalType object will be needed in the processing that is done by the class. This object will be used to contain the base enum that tells Axapta the type of journal to create. This information is passed from the Windows application that you are creating.

Created Needed Methods

The rest of the class will consist of two methods. One will be used to convert a string, which is passed in from the Windows application, into a base enum that is needed for the rest of the processing. The second method is used to convert the string value that defines the desired ledger type into the required base enum value.

To create a method within this class, start by double-clicking the AxLedgerDemo class. This will open the X++ code editor. Next, click the first left icon in the editor toolbar. This will create a new method within the X++ editor. Modify the code in the X++ editor to match the following example:

LedgerJournalType convertType(str _value)
{
  LedgerJournalType  ledgerJournalType;
  ;
  str2Enum(LedgerJournalType,_value);   // convert string to enum value
  return ledgerJournalType;        // return our enum value
}

This is the method that converts the string value that defines the desired ledger type into the required base enum value.

Save the method code by clicking the disk icon that is displayed in the X++ editor toolbar.

Next, create another new method. Modify the code to match the following example:

str ProcessLedgerJournal(str _type, str _name, str _CurrencyCode, str _AccountNum, AmountMST _DebitAMT, str _offset)
{
  str     returnStr;
  ;
  journalType = this.convertType(_type);

  ttsbegin;
  select firstonly ledgerjournalName where ledgerJournalName.JournalType == journalType;
  ledgerJournalTable.JournalName = LedgerJournalName.JournalName;
  ledgerJournalTable.initFromLedgerJournalName();
  ledgerJournalTable.Name = _name;
  ledgerJournalTable.insert();

  numberSeq = NumberSeq::newGetVoucherFromCode(ledgerJournalName.VoucherSeries);
  ledgerJournalTrans.voucher = numberSeq.voucher();

  ledgerJournalTrans.JournalNum = ledgerJournalTable.JournalNum;
  ledgerJournalTrans.currencyCode = _CurrencyCode;
  ledgerJournalTrans.ExchRate = Currency::exchRate(ledgerJournalTrans.currencyCode);
  ledgerJournalTrans.AccountNum = _AccountNum;
  ledgerJournalTrans.Dimension[1]= 'Admin';
  ledgerJournalTrans.AccountType = LedgerJournalACType::Ledger;
  ledgerJournalTrans.AmountCurDebit = _DebitAMT;
  ledgerJournalTrans.TransDate = today();
  ledgerJOurnalTrans.Txt = 'AxLedgerDemo test';
  ledgerJournalTrans.OffsetAccount = _offset;
  ledgerJournalTrans.insert();
  returnStr = ledgerJournalTable.JournalNum;

  ledgerJournalCheckPost = ledgerJournalCheckPost::newLedgerJournalTable(ledgerJournalTable,NoYes::Yes);
  ledgerJournalCheckPost.run();

  returnStr += ' should have posted. Please check within Axapta to verify.';
  ttscommit;

  return returnStr;      // send back results
}

This code is the heart of the process. The code retrieves the information that is passed to it by the external application, finds the journal type, creates the needed records in the tables, populates the required fields, and posts the ledger journal.

Save the method code by clicking the disk icon that is displayed in the X++ editor toolbar.

Visual Basic 2005 Application

The first step in creating this application is to create a new project within Visual Studio 2005. Call the project AxLedgerDemo. After you create the project, you must create a reference to the Axapta Business Connector in the project. In Visual Studio, navigate to the Project menu, click Add Reference, and then click the COM tab.

Locate the Business Connector by finding Axapta COM Connector 1.2 Type Library in the list. Highlight this item, and then click Select. After the component appears in the Selected Components list, click OK.

Building the Form

On the form, create the following controls, by dragging them from the Toolbox, and changing the properties of each control to match the following:

  • Combobox named JournalType. The Items property collection should contain the following values: Daily, weekly, monthly.
  • Textbox named JournalName. No default text.
  • Combobox named Currency. The Items collection should contain the following values: USD and EUR.
  • Textbox named Amount. This will be the debit amount.
  • Textbox named PostingAccount. This will be the posting account in Axapta.
  • Textbox named OffsetAccount. This is the offset posting account in Axapta.
  • Button called Process. The Click method will be where the code resides for our Axapta integration.

Making the Connection

The first step is to effect recognition of the business connector object within the code portion of the Windows application. To do so, make the following declaration:

Dim Axapta As AxaptaCOMConnector.Axapta

This allows the application to use the Axapta variable to refer to the business connector objects.

Creating the Ledger Journal in Axapta

At this point, the Windows application should have all the controls that it needs to function. The next step is to take the information from the controls, and send it to Axapta for processing. Do this by using the Click method of the Process button.

Here is the code for the Click method of the Process button:

Private Sub Process_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Process.Click
    Dim AxLedgerDemo As AxaptaCOMConnector.IAxaptaObject
    Dim AxResults As String
    'connect to Axapta by using the COM connector
    Axapta = New AxaptaCOMConnector.Axapta
    Axapta.Logon("Admin", "", "", "")
    AxLedgerDemo = Axapta.CreateObject("AxLedgerDemo")
    Try
      AxResults = AxLedgerDemo.Call("ProcessLedgerJournal", JournalType.SelectedItem.ToString, JournalName.Text, Currency.SelectedItem.ToString, PostingAccount.Text, Amount.Text, OffsetAccount.Text)
      MsgBox(AxResults)
    Catch ex As Exception
      MsgBox(ex.Message.ToString, MsgBoxStyle.Critical, "Error Message")
    End Try

    Axapta.Logoff()
  End Sub

The following two lines are used as variable declarations. The first line is used to "hold" and reference the instantiated Axapta object. The second variable is used to hold the results of the operation, as returned by Axapta.

Dim AxLedgerDemo As AxaptaCOMConnector.IAxaptaObject
Dim AxResults As String

The following lines actually are used to make the connection to Axapta through the Business Connector. The first instantiates the object, and the second calls the logon method of the object. Please note that the Admin value in the call is the CONFIGURATION being used for logging in, NOT the user name. For more information, see the Axapta Developers Guide (from within Axapta, navigate to the Help menu and click Axapta Developers Guide).

Axapta = New AxaptaCOMConnector.Axapta
Axapta.Logon("Admin", "", "", "")

The next lines are used when the actual Axapta objects (Class and methods) created within Axapta are called. The first line instantiates the Axapta object, and the Try – Catch block is used for rudimentary error trapping. AxLedgerDemo.Call is used to call the ProcessLedgerJournal method of the AxLedgerDemo class, and the six values following the method name are the parameters being passed into the method.

AxLedgerDemo = Axapta.CreateObject("AxLedgerDemo")
    Try
      AxResults = AxLedgerDemo.Call("ProcessLedgerJournal", JournalType.SelectedItem.ToString, JournalName.Text, Currency.SelectedItem.ToString, PostingAccount.Text, Amount.Text, OffsetAccount.Text)
      MsgBox(AxResults)
    Catch ex As Exception
      MsgBox(ex.Message.ToString, MsgBoxStyle.Critical, "Error Message")
    End Try

If the processing goes as planned, the results that are passed back to the Windows application will be displayed to the user. If there is an error in processing, the catch section actually traps the error returned by Axapta, and displays it to the end user.

Finally, the following line closes the connection through the business connector into Axapta.

Axapta.Logoff()

After the result has been returned to the Windows application, the information should be available within Axapta. To check this from within Axapta, open the Main Menu, navigate to General Ledger, click Journals, and then click General Journal. Change the Show dropdown menu to display Posted, and verify that the journal number that was returned by the Windows application exists. If so, highlight the journal, and click the Lines button. A new form should open, displaying the journal entry that was created by the Windows application.

Where to Go from Here

This paper has introduced you to the concept of creating ledger journals within Microsoft Axapta. The methodology used to create this Windows application is readily transferable to creation of a Web application. You can see the possibilities.

As a caution, we need to remind you that virtually no error checking was done within this application, and only very rudimentary error trapping. To make this a truly usable application, you would need to greatly expand both the error checking and error trapping routines. Our purpose here was just to show you, as simply as possible, how to use an external application to create a Windows application that would create and post ledger journal entries within Microsoft Axapta.

Conclusion

Integration into Axapta can take many different forms and can be accomplished by many different methods. This paper briefly demonstrated concepts that are viable options between both Windows and Web applications. The most critical step during the integration is determining the objects within Microsoft Axapta that are required to perform the operations that you want to implement. When that is done, the rest of the steps are straightforward code generation and form design.