Stephen Smith's Blog

Musings on Machine Learning…

Posts Tagged ‘session object

An Introduction to the Sage 300 ERP .Net API

with 162 comments

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.

vs1

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.

Advertisements

Written by smist08

October 12, 2013 at 4:57 pm

Opening Sage 300 ERP Sessions

with 30 comments

Introduction

Sage 300 ERP has a number of very flexible external APIs that allow programs to access all the business logic in the program. The business logic is stored in Views that are accessed via a standard API. To start using the business logic from one of our external APIs you first need to sign-on to the API and establish a session. This article is going to only talk about the AccpacCOMAPI which is our main COM API. Sage 300 ERP has an older COM API usually referred to as a4wcom, so be sure to use the newer one we are talking about here. Many of the concepts can be adapted to other APIs like the .Net or Java APIs. However to interact with other COM components like the session manager you must be using the AccpacCOMAPI. The examples in this posting will all be in Visual Basic 6.

This API has been around for a long time, but we recently received quite a few queries through customer support on establishing connections. So I thought it might be worth while writing a blog post on some of the use cases we try to support, some of the functionality that perhaps isn’t very widely known as well as the reasons for why some aspects work like they do.

For a bit more background on the Sage 300 business logic have a look at this blog posting.

Libraries

Sage 300 ERP’s COM API can be used by any tool that understands COM and how to talk to COM objects. The first step is to add the COM object to your project. In VB6 you do this by going to Project – References and adding “ACCPAC COM API Object 1.0”. In some tools you can browse to the DLL and add that, in this case you browse to where ever you installed Sage 300 ERP and then browse for runtime\a4wcomex.dll.

Creating and Initializing

Once you have the library available for you, now you need to get started. All objects in our COM API are created via APIs in our COM API. But first you need to get started by creating and initializing a session object. This is the root object and from this everything else is derived. In VB there are a couple of ways to create the initial session object either:

Dim mSession As New AccpacCOMAPI.AccpacSession

Or

Dim mSession As AccpacCOMAPI.AccpacSession
Set mSession = CreateObject(“Accpac.Session”)

Once you have a session object then you need to initialize it:

mSession.Init “”, “XY”, “XY1000”, “61A”

If you are accessing the COM API from an external program and not an SDK application then the parameters don’t matter. The first parameter is for when an SDK application is run from the desktop to connect them up properly and the other parameters are similarly for SDK application for other APIs like getting you applications help files correctly. Generally for an external application you just want these set with valid value so things will proceed. The application ID “XY” is reserved for non-SDK application to use, so you don’t have any risk of having things confused with a third party application. It is important that you call init before doing anything else. If you do call some other method first then expect to get strange error messages.

Below is the object model of all the objects you can get from an initialized session:

objectmodel

Company List

At this point we still haven’t signed into a company. At this point you can really just sign-on, but you can also get a list of companies that you can sign-on to. This is the API used by Sage 300 to build sign-on dialogs. In the session object is an organizations collection that you can traverse to get the information on the available companies.

For i = 0 To mSession.Organizations.Count – 1
Print mSession.Organizations.ItemByIndex(i).DatabaseID,
mSession.Organizations.ItemByIndex(i).Name
Next i

As you can see by the code, this API was invented by a C programmer and not a VB programmer.

Signing On

The main way you sign-on to a company is to use the open method.

mSession.Open “ADMIN”, “ADMIN”, “SAMLTD”, Date, 0, “”

The main thing you need for this method is the user id, password, company id and session date. After calling this, the next thing you usually do is create a database link and then from the database link create your view objects. Now you can call the views and use all the Sage 300 business logic. The disadvantage of this method is that you need to know the user id and password. But otherwise you are good to go.

Session/Signon Managers

Of course with what we have discussed so far you could create your own sign-on dialog. But why re-invent the wheel. The main Sage 300 ERP COM library is intended to be called from both user interface programs or server processes, as a result it has no user interface functions itself, it will never popup a messagebox or a dialog box. It is strictly processing and no UI.

However we do provide a number of other ActiveX controls that are intended to be used as UI components. Two of these are the Signon Manager and the Session Manager. You only interact with the Session Manager and then the Session Manager uses the Signon Manager whenever it needs it.

So if you don’t want to have to know the user id and password then you use the Session Manager to create your session for you and you get back a session that has been created, initialized and opened for you. The user will be able to enter their user id, password and select the company and session date to use for processing.

To use the Sesion Manager you need to add a reference for “ACCPAC Session Manager 1.0” or access the runtime\a4wSessionMgr.dll. Then you would write some code like:

Dim signonID As Long
Dim mSession As AccpacCOMAPI.AccpacSession
Dim sessMgr As New AccpacSessionMgr

sessMgr.AppID = “XY”
sessMgr.ProgramName = “XY1000”
sessMgr.AppVersion = “54A”
sessMgr.CreateSession “”, signonID, mSession

The intent of the session manager was to facilitate things like workflow management. So the first time someone accesses it, it will create new session and the user will get a signon dialog. However the next time it is accessed, you will just get back the session the user opened the first time. This allows applications to be strung together in a workflow type manner without each step requiring the user to sign-on. If you do want a fresh sign-on, you can set the ForceNewSignon property to true. If there are two desktops signed in and ForceNewSignon is false, then the user will get a dialog box to choose which session they want.

Summary

The external APIs to Sage 300 ERP are very powerful. Since the AccpacCOMAPI is used exclusively by our VB forms to access the Sage 300 business logic, you know that from this interface you can do anything that can be done from a regular UI. All business logic is exposed this way. So the intent of this posting was just to give you a little help in getting started to get at all that business logic.