Wednesday, 24 February 2016

Contract-Based Web Services API

Hi Everyone.

Today I want to speak with you about new Contract-Based Web Services API that you can use in Acumatica 5.3 version.
The main differences between previous Screen-Based API and new AP:

  1. Previously you had to use names of fields and actions right from Acumatica UI. And if we rename or move field your code will stop working. Now new API has an intermediate layer between Acumatica UI and the integration code, so can be sure that most of minor changes in Acumatica code will not break existing integration.
  2. New API is easier to use. You need less lines to complete the same task. Also it is more intuitive, so it will easier for you to write a code.
  3. The current API just isn’t well adapted to REST. But now you can feel very strong industry trend toward to REST.

So now you have intermediate layer that we call "Endpoint", We will keep and evolve default (build-in) endpoint that can be used for most of common task, but if you need more complex or specific logic than you have 2 options:
  • You can configure new one in Acumatica user interface. (Fast and flexible, but requires support).
  • Ask us to add new logic to default endpoint. (Long, but much easier to use and support)

Endpoint contains screens, linked/detail contains, field and actions. All these items has names that will be expanded through web services. On the other side all these items connected with Acumatica user interface elements.

When everything required is mapped you can start to use web service.
In this example i will show you how to use Stock Items thought API. For my task it is enough to use default endpoint, so i will use it.

If you click on "View Endpoint Service" you will see web services definition with all possible methods. The main thing that you need at this point of time is URL of web service. 
You will use this url in Visual Studio (Or other environment) to import web service definition.

And the last preparation step - do not forget to enable cookies and increase request limit.

Now we can start development.
Here you can find code example that will show you some basic scenarios of using contract-based web services. You can copy it to your project in Visual Studio and try to play around

Code Example:

The classic web services API is not going anywhere and will remain supported. But it is better to built all new projects on the new contract-based web services API – sometimes next year it will become mandatory for solution certification. 
Existing code can be migrated gradually; you can mix both technologies in the same product (You can share session cookies to avoid needing multiple logins).

Have a nice integration!

7 comments:

VANNAK said...

I want to limit record load in Entity[] items = client.GetList(new StockItem(), false). Could you explain how to load this with 20 record from acumatica. Thank

Sergey Marenich said...

HI Vannak,
As i know there is no function to limit number of records in CB API. However there are some workaround options:
- Use filter to limit number of records
- Use GI to create an inquiry that shows only top 10 records and use in with API
- use Screen Based API.

Hope it helps.

Kapil Kulkarni said...

How to add Bills as a line items for Bill Payment using CB API

jwleys said...

For the contract-based web-services API, what would you suggest in-terms of helper / stub classes for PHP.

The Screen based web-services API has Acumatica PHP helper files:

1) acuwsdl2php.php
2) AcumticaGate.php
3) CustomerCreate.php
4) CustomerSelect.php
5) CustomerSelectAll.php
6) LeadCreate.php

This is particularly needed with the screen based web-services API as there are multiple WSDLs, one for each screen. Would I be right in assuming that with the contract based API generating stub-classes using:

1) http://pear.php.net/reference/SOAP-0.9.4/SOAP/SOAP_WSDL.html#methodgenerateProxyCode
2) https://www.wsdltophp.com/

Would be more feasible? Or do you have new PHP helper for the contract based web-services

hayedid said...

Hello. Thank you for your blog. Would you mind doing a blog that explains how to setup your endpoints (I am trying to automate some Vendor reads and adds) for Acumatica 5.0?

Thank you.

abanoub labeeb said...

I used the code on the I200-Screen-Based-Web-Services-6.0.pdf guide to export every customer , Inventory Item , Prices , ... in the system and store them locally to be used in a local system

this works with small amount of data but not big amount of data like 5 years stored customer data it takes very long time then gives an exception with the message :

The operation has timed out ,

And stack Trace :

at System.Web.Services.Protocols.WebClientProtocol.GetWebResponse(WebRequest request) at System.Web.Services.Protocols.HttpWebClientProtocol.GetWebResponse(WebRequest request) at System.Web.Services.Protocols.SoapHttpClientProtocol.Invoke(String methodName, Object[] parameters) at ERPPOS.STOREPOS.Screen.AR303000Export(Command[] commands, Filter[] filters, Int32 topCount, Boolean includeHeaders, Boolean breakOnError) in e:\2B\POS\ERPPOS\ERPPOS\Web References\STOREPOS\Reference.cs:line 1619 at POS.Customer.ExportAllCustomers(Screen context) in e:\2B\POS\ERPPOS\ERPPOS\POS\Integration\Customer.cs:line 445 at POSVer1.ConfigurationSync.SyncCustomersConfiguration() in e:\2B\POS\ERPPOS\ERPPOS\POS\Utility\SyncUtility\ConfigurationSync.cs:line 42

then i have specified Timeout to a big number ,

it takes very long time then gives an exception with the message :

Client found response content type of '', but expected 'text/xml'. The request failed with an empty response. And the stack Trace :

at System.Web.Services.Protocols.SoapHttpClientProtocol.ReadResponse(SoapClientMessage message, WebResponse response, Stream responseStream, Boolean asyncCall) at System.Web.Services.Protocols.SoapHttpClientProtocol.Invoke(String methodName, Object[] parameters) at ERPPOS.STOREPOS.Screen.AR303000Export(Command[] commands, Filter[] filters, Int32 topCount, Boolean includeHeaders, Boolean breakOnError) in e:\2B\POS\ERPPOS\ERPPOS\Web References\STOREPOS\Reference.cs:line 1619 at POS.Customer.ExportAllCustomers(Screen context) in e:\2B\POS\ERPPOS\ERPPOS\POS\Integration\Customer.cs:line 445 at POSVer1.ConfigurationSync.SyncCustomersConfiguration() in e:\2B\POS\ERPPOS\ERPPOS\POS\Utility\SyncUtility\ConfigurationSync.cs:line 42

Please Advice .

Sergey Marenich said...

Hi Abanoub,
As in many other systems, when it comes to huge amount of data, you need to use different approach and limit number of records you can export.
Please see here and example of how you can select data in batches
https://stackoverflow.com/questions/46353867/exporting-records-from-acumatica-via-soap-contract-based-api

With ReturnBehavior set to OnlySystem or OnlySpecified you can also define what parts of an entity should be exported. After you export IDs and keys in batches, record-specific data can be further requested with the Get method.

Hope it helps!