An Introduction to the Sage 300 ERP .Net API

Introduction

I’m planning to write a series of blog articles on the Sage 300 ERP API and in particular on the .Net API that has been part of Sage 300 since version 5.1A. I have a couple of goals with these articles:

1. Provide a deeper and more complete explanation of many parts of our API. Although all the samples in this series will be in C# and use the .Net API, the ideas will apply to integrating to Sage 300 via any of our other APIs including COM, Java, XAPI, etc.
2. Explore a number of newer .Net technologies and look at how these can be integrated to Sage 300. These may include things like LINQ and ASP.Net MVC.

The goal is to start simple and then to progress to deeper topics. I’m sure I’ll have blog postings on other topics in-between, but look for this series to continue over time.

I’ll be developing all these projects using the latest C#, Visual Studio and .Net framework. I’ll post the full project source code for anything mentioned. So to start these will be Visual Studio 2012, but I’ll switch to 2013 after it’s released. I’m also currently running Sage 300 ERP 2014, but these examples should work for version 5.6A and later.

Caveats

When you use the Sage 300 .Net interface you can’t share any objects with Sage 300 COM objects or ActiveX screen controls we use in our VB6 programming framework. If you want to use any of the COM/ActiveX controls then you must use the Accpac COM API. When you use the .Net interface you don’t have any interoperability with the other VB6 related technologies. From .Net you do have full access to our COM API via .Net’s COM Interop capability.

Generally this is ok. If you are integrating a .Net product or writing an integration to something like a Web Server then you don’t want any of this anyway. But to just point this out up front. That you cannot use a .Net session object anywhere in a COM/ActiveX API. The COM/ActiveX session object is something that is similar but not interchangeable.

Documentation and Samples

Some versions of Sage 300 have included the help file that contains the .Net interface reference manual. However this isn’t universally available. To help with this I’ve put a copy on Google Drive for anyone that needs it, located here. Note that when you download help files over the Internet, Windows will mark them as dangerous and they may not open, to get around that, have a look at this article.

Of course within Visual Studio, since our API is completely standard .Net, you will get full Intellisense support, so Visual Studio can give you a list of property and method names as you type along with giving you the argument list for the various methods.

I’ll make the projects that are described in this series of blog posts available here. The one for this article is WindowsFormsApplication3 which then reminds me I should fill in the dialog box properly when I create a new project.

There is additional documentation on our DPP Wiki, but you need to be a member of the DPP program to access this.

Project Setup

First you must have Sage 300 ERP installed and you not have de-selected the “Sage 300 ERP .Net Libraries” in the installation program when you installed the product. Then after you create your Visual Studio project (of whatever type it is), you need to add two references: ACCPAC.Advantage.dll and ACCPAC.Advantage.Types.dll. Both of these will have been installed into the .Net GAC. It’s usually worth adding a “using ACCPAC.Advantage;” statement to the beginning of source files that access our API, since it saves a lot of typing of ACCPAC.Advantage.

Now you are ready to use the Sage 300 ERP API. In this first articles I’m going to create a simple .Net Windows Forms C# application, put a button on the form and on click exercise various parts of the API. Nothing exciting will happen but we will print out some output to the console to see whether things are working.

Creating and Using a Session Object

I talked a lot about creating sessions in this article, mostly from the COM point of view. Now we’ll recap a bit, but from the .Net point of view. The first thing you need to do when using our API is to create and initialize a session object.

using ACCPAC.Advantage;

private Session session;

session = new Session();

session.Init("", "XY", "XY1000", "62A");

At this point you have a session that you can use. For our purposes here session.Init is very important that it is called and nothing else will work until it is called, but the parameters aren’t that important at this point. We’ll come back to them later, but you can just use the ones in the above example for most purposes.

Although we aren’t signed on yet there are still some things we can do with the session object like get a list of the companies, which is something that is required to build a signon dialog box.

foreach ( Organization org in session.Organizations )

{

   Console.WriteLine("Company ID: " + org.ID + " Name: " +

       org.Name + " Type: " + org.Type);

}

Notice that the session’s Organizations property is a standard .Net collection and as a result we can use any C# language support for dealing with collections such as the foreach statement shown. Generally in our API we’ve tried to make sure everything is presented in a standard way for .Net programmers to use. Another very useful collection on the session is the Errors collection which is a collection of all the error messages (including warnings and informational) since it was last cleared. We’ll cover the usefulness of the Errors collection in a future article.

Now let’s actually sign on to Sage 300:

session.Open("ADMIN", "ADMIN", "SAMINC", DateTime.Today, 0);

Basically you need to provide the same sort of information that a user would sign-on to the desktop. Note that although the user id and password are forced to uppercase in the desktop’s sign-on dialog, they are actually case sensitive at the API level, so you must enter these in upper case. Also note that the session date is given as a standard .Net date type.

Now that you are signed on, you can start to do more things. We can now start to access the database. This API was created before we duplicated the system database into the company database, but from the session you can get at some old system database tables like the currencies (which are now read from the copy in the company database). But to really start using the database you need to create a DBLink object from the session object. To do this you specify whether you want a link to the company or system database (which will pretty much always be Company now). Plus you specify some flags, like whether you need read-write or read-only access.

private DBLink mDBLinkCmpRW;

mDBLinkCmpRW = session.OpenDBLink(DBLinkType.Company, DBLinkFlags.ReadWrite);

Now that we have a database link we can directly access some things like the company information, fiscal calendars and the list of active applications for this company. But the main use of this object is to open the Sage 300 ERP business logic objects which we typically call Views.

Summary

So far we’ve only managed to open a session and start using a few basic .Net objects. But these are the starting point to any project so we needed to take a bit of time to set the stage for future articles. Next time we’ll start to create View objects from our DBLink objects and start to explore some View functionality.

If you have any opinions on the coding style, the use of C# or any other questions, please leave a comment for the article and I’ll try to address them.