AcumatiCares
In today’s post, I’m going to introduce you to Acumatica’s Cloud ERP APIs which allow for integration with external systems and applications. Through web services, external applications can get data records from Acumatica, process these records, save, create new or updated records. Today, we make available to the developer and system integrator access to both screen-based and contract-based APIs which are based on SOAP interfaces. In the near future, we will be rolling out our REST-enabled contract-based APIs – where developers will be able to use REST interfaces. I’ll be going into some depth in a future blog post, providing more detail of our implementation of REST. Figure 1 below graphically represents these API interfaces between our core Enterprise Resource Planning (ERP) product base and third party applications.
Screen-based Web Services API
Our screen-based APIs are designed to work with all of our Acumatica ERP forms by using the fields and actions available on these forms directly. For example, in the form below, each element – a text box, combo box, or table column is associated with a particular web services API class and is available through a corresponding property of this class. The property has a similar name to that of the corresponding box on the form.
After you have logged into Acumatica by using the API, you can access the data on the forms available through a simple web service. We provide a screen class of the API methods for working with all Acumatica ERP forms available through the service. You can find out which form a method accesses by the prefix in the name of the method, which is the form ID. For example, the Export() method that you use to export data from the stock items from the inventory form IN202500 is IN202500Export().
Screen-based Code Sample: Retrieving a List of Stock Items
Let’s take a look at a sample code example where we retrieve a list of stock items from inventory using the Screen-based API.
//Retrieving the list of stock items from inventory
public static void ExportStockItems()
{
using
{
//Connect to the web service and log in to Acumatica ERP
Screen context = WebServiceConnector.InitializeWebService()
}
{
try
{
IN202500Content stockItemsSchema = context.IN202500GetSchema();
var commands = new Command[]
{
stockItemsSchema.StockItemSummary.ServiceCommands.EveryInventoryID,
stockItemsSchema.StockItemSummary.InventoryID,
stockItemsSchema.StockItemSummary.Description,
stockItemsSchema.GeneralSettingsItemDefaults.ItemClass,
stockItemsSchema.GeneralSettingsUnitOfMeasureBaseUnit.BaseUnit,
new Field
{
ObjectName =
stockItemsSchema.StockItemSummary.InventoryID.ObjectName,
FieldName = “LastModifiedDateTime”
}
};
}
finally
{
context.Logout();
}
}
}
Note that the line in the code above, IN202500Content stockItemsSchema = context.IN202500GetSchema(); references the Inventory screen (IN2025000) and it’s content and therefore is tied to a specific screen which is the screen or form we showed previously in figure 2.
Screen-based APIs are unique to Acumatica – they offer tremendous value in terms of a set of rich capabilities and great flexibility. However, they are screen-bound and any change in the screen tends to change the API itself. For example, moving a control from one group to another – adding a small border may force you to recompile your code in order to ensure that everything is working properly. Everything that can be done at the screen-level in Acumatica can be done with the Screen-based API. Meaning you can automate almost any activity or task. Let’s us now take a look at our contract-based APIs.
Contract-based Web Services API
These APIs were introduced in Acumatica 5.3 back in February of this year and are relatively new. Contract-based APIs operate with business logic objects not bound to the screen, per se – and their properties and methods. Contract-based APIs are built on an object model that the web services API provides. They do not change based on system customization, localization, or any other changes made to Acumatica Enterprise Resource Planning (ERP) such as forms.
For example, suppose that you wrote some code using the ItemClass field, which accesses the same ItemClass ID element we found in the Inventory form IN2025000 in our screen-based API example. If you change the name of the ItemClass ID element in your customization project, your code remains fully functional and does not require recompilation, nor require any further modifications. You can access the ItemClass ID element on the form through the same ItemClassID field.
Simple Contract-based Code Sample: Retrieving a List of Stock Items
Like the screen-based example in the previous section above, we show here how easy it is to retrieve stock items from inventory. Note the differences between the code. Here our code does not reference a screen to retrieve the items and is very simple and straightforward.
//Retrieving the list of stock items from inventory
public static void ExportStockItems()
{
using (DefaultSoapClient soapClient = new DefaultSoapClient())
{
//Log in to Acumatica ERP
WebServiceConnector.InitializeWebService(soapClient);
try
{
//Get the list of stock items
Entity[] stockItems =
soapClient.GetList(stockItemsToBeFound, False);
}
finally
{
//Log out from Acumatica ERP
soapClient.Logout();
}
}
}
For any new development projects from our current partners or your first development project as a new partner, should be built using the contract-based APIs. However, some features of the system are not exposed yet. Thus, you will on occasion still use some of the screen-based APIs. Using the newer contract-based APIs provide added stability – not susceptible to problems created by making changes in your application or what we may change on our side that may affect the functionality of your applications without recompilation. Of course it should go without saying: it is important to always test your applications when a new version of the product is released, not just during your development cycle.
Summary
Screen-based APIs are unique to Acumatica – think of them as a kind of scripting interface to get data in and data out of our system platform. Most importantly, remember they are screen-bound. Every Acumatica screen has fields, groups and containers…and so on. Every change in the screen tends to change the API. For example, moving a control from one group to another – making small changes to the form or code can cause the application to not function as designed – recompile your code to ensure this. With these APIs, you get tremendous flexibility and rich functionality. Everything that can be done at the screen-level can be done with the API as well, giving you the ability to automate almost anything in the system.
With the release of the contract-based APIs, we expose our data models – e.g. CRUD, details, and simple methods – that are strictly defined. You can create an entity, update, read by criteria, by key identifiers, etc. We have exposed and defined our data model, which the developer can take advantage of without worrying about screen changes that may conflict and break the application. We encapsulate changes and hide the complexity from the developer. We have essentially provided a “contract” with developers that promises that any underlying changes we make won’t break their code.
By listening to the feedback from our customers and partners, we released our contract-based APIs this past February. Soon, we will release our REST-enabled contract-based APIs which have a number of added benefits developers are excited about. We will be providing more detail in future posts to this blog. We’ll be releasing a video discussion on our APIs very shortly, including an early look at REST support.
Reiterating an important message to our readers: any new integrations, any new development projects started should be built using the contract-based APIs. Although, we are investing our efforts in contract-based APIs, the screen-based APIs will continue to be maintained for the foreseeable future. We expect our current partners’ code to migrate over time to take advantage of the benefits of our contract-based APIs.
For more details, download our Developer Guide . If you have questions, visit our developer forum up on StackOverflow and post any questions you may have.
