Acumatica 2018 R2 Developer Enhancements: Web Services Project Integrations

Mark Franks | September 25, 2018

In following up my post on Developer Focused Enhancements in Acumatica 2018 R2 that we launched last week, it warrants a closer look at the Web Services enhancements that were made in more detail, including an early peak of our Postman REST Starter Kit – a collection of requests we’re providing to help jump start working with the REST API in Acumatica.

Acumatica 2018 R2 Developer Enhancements: Web Services Project Integrations

Last week I highlighted the enhancements of the Web Services Endpoints – what’s new, what’s been modified, or no longer supported. This week I’ll provide some examples/scenarios of ERP projects with various external systems.

Acumatica ERP Project Integrations with External Systems

You can use contract-based REST & SOAP APIs for integration of Acumatica ERP projects with a variety of external systems. Some examples include sending pro formas by eMail, managing of account groups, running project billings, creating GL transactions with project codes that don’t produce project transactions, and time entries to name a few.

We document in detail all the project scenarios enumerated above. Many of the new endpoints that I wrote about in my last post are used in the project integration examples. To give you a taste of what we are providing our developer community, let’s take a look at one of the examples in detail, including the necessary code using the REST API.

Sending Pro Formas via eMail

In accounting, pro forma refers to a statement of a company’s financial doings, that excludes unusual or nonrecurring transactions, when reporting the company’s earnings. Excluded expenses typically include declining investment values, restructuring costs and adjustments made on the company’s balance sheet that fix faulty accounting practices from other years¹.

In our example scenario, a construction company uses an integrated solution of Acumatica ERP with an external payroll system. A project manager of the company needs to send pro forma invoices to the clients by email. Through the contract-based REST & SOAP API, external systems can create pro formas and send them out via email.

To accomplish this, a pro forma from a project is needed. The project must have the following specified: CustomerBillingRuleBillingPeriod, and NextBillingDate and must have an Active status. Because of data validation in the project, NextBillingDate cannot be specified for a project with an On Hold status, and you cannot change the customer in a particular project with an Active status. However, these settings can be specified in multiple API calls, as shown in the code examples illustrated below.

Also, it should be pointed out that ProFormaInvoice cannot be created by using the PUT HTTP method or the Put() SOAP API method, but can through the invocation of the RunProjectBilling action of the project entity. Because there is no mapping for email settings in the Project entity, you have to prepare a project template with the specified email settings on the Project Templates (PM208000) form and then use this template for creation of the project through the API.

To work through this scenario, configure your client application and an Acumatica ERP instance in the following four steps:

  1. Deploying a new Acumatica ERP instance with the SalesDemo dataset inserted.
  2. Enable the Enable/Disable Features (CS100000) form
  3. In the client application, add a service reference to the Default/18.200.001 system endpoint.
  4. Sign into the instance of the client application and use the company name (which you specified when you created the instance) and use the PRODWHOLE branch.

REST API Requests

Now you can use the following sequence of example code of HTTP requests to create a pro forma and send it by email through the contract-based REST API.

Please note the new endpoints used in the example [Project, ProFormaInvoice, AccountGroup, and ProjectTask] as you review the code below.

1. Create a project from a template and specify CustomerBillingRule, and BillingPeriod of the project.


PUT [/]/entity/Default/18.200.001/Project
HTTP/1.1
Host: 
Accept: application/json
Content-Type: application/json
{
“ProjectID” : {“value” : “TESTPR3”},
“ProjectTemplateID” : {“value” : “TM-PROFORM”},
“Customer” : {“value” : “ABARTENDE”},
“BillingAndAllocationSettings” :
{
“BillingRule” : {“value” : “FIXEDPRICE”},
“BillingPeriod” : {“value” : “Month”},
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{ … }

2. Make the project active.


PUT [/]/entity/Default/18.200.001/Project
HTTP/1.1
Host: 
Accept: application/json
Content-Type: application/json
{
“ProjectID” : {“value” : “TESTPR3”},
“Hold” : {“value” : false}
}
HTTP/1.1 200 OK
Content-Type: application/json
{ … }

3. Specify NextBillingDate of the project.


PUT [/]/entity/Default/18.200.001/Project
HTTP/1.1
Host: 
Accept: application/json
Content-Type: application/json
{
“ProjectID” : {“value” : “TESTPR3”},
“BillingAndAllocationSettings” :
{
“NextBillingDate” : {“value” : “2018-08-16T04:21:45.787+03:00”},
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{ … }

4. Activate a project task.


PUT [/]/entity/Default/18.200.001/ProjectTask
HTTP/1.1
Host: 
Accept: application/json
Content-Type: application/json
{
“ProjectTaskID” : {“value” : “01”},
“ProjectID” : {“value” : “TESTPR3”},
“Status” : {“value” : “Active”},
}
HTTP/1.1 200 OK
Content-Type: application/json
{ … }

5. Create a project transaction and invoke the release of the transaction.


POST [/]/entity/Default/18.200.001/
ProjectTransaction/ReleaseTransactions HTTP/1.1
Host: 
Accept: application/json
Content-Type: application/json
{
“entity” : {
“Details” :
[
{
“Project” : {“value” : “TESTPR3”},
“ProjectTask” : {“value” : “01”},
“CostCode” : {“value” : “0000”},
“AccountGroup” : {“value” : “LABOR”},
“Qty” : {“value” : 10},
“Amount” : {“value” : 10},
},
]
}}
HTTP/1.1 202 Accepted
Location: [/]/entity/Default/18.200.001/
ProjectTransaction/ReleaseTransactions/status/ce6a7728-5f8e-416fbbe5-617d2725465c

6. Use the URL from the Location header to obtain the status of the long-running operation. When the GET HTTP method with this URL returns 204 No Content, the operation is completed.


GET [/]/entity/Default/18.200.001/
ProjectTransaction/ReleaseTransactions/status/ce6a7728-5f8e-416fbbe5-617d2725465c HTTP/1.1
Host: 
Accept: application/json
Content-Type: application/json
HTTP/1.1 204 No Content

7. Invoke project billing to create a pro forma.


POST [/]/entity/Default/18.200.001/Project/
RunProjectBilling HTTP/1.1
Host: 
Accept: application/json
Content-Type: application/json
{
“entity” : {
“ProjectID”: {
“value”: “TESTPR3”
},
}
}
HTTP/1.1 202 Accepted
Location: [/]/entity/Default/18.200.001/
Project/RunProjectBilling/status/6952c6d1-04be-4330-a26e-c6b855ba332c

8. Use the URL from the location header to obtain the status of the long-running operation. When the GET HTTP method with this URL returns 204 No Content, the operation is completed.


GET [/]/entity/Default/18.200.001/Project/
RunProjectBilling/status/6952c6d1-04be-4330-a26e-c6b855ba332c HTTP/1.1
Host: 
Accept: application/json
Content-Type: application/json
HTTP/1.1 204 No Content

9. Obtain the list of pro formas of the project (which currently contains only one pro forma) by adding:


$expand=Invoices to the endpoint address. For details about parameters, see Parameters for Retrieving
Records.
GET [/]/entity/Default/18.200.001/Project/
TESTPR3?$expand=Invoices HTTP/1.1
Host: 
Accept: application/json
Content-Type: application/json
HTTP/1.1 200 OK
Content-Type: application/json
{ … }

10. Send the pro forma by email.


POST [/]/entity/Default/18.200.001/
ProFormaInvoice/EmailProFormaInvoice HTTP/1.1
Host: 
Accept: application/json
Content-Type: application/json
{
“entity” : {
“RefNbr”: {
“value”: “PF00008”
},
}
}
HTTP/1.1 202 Accepted
Location: [/]/entity/Default/18.200.001/
ProFormaInvoice/EmailProFormaInvoice/status/a4caa455-0eed-4c11-
A5a9-2a8333e53db1

11. Monitor the status of the operation.


GET [/]/entity/Default/18.200.001/
ProFormaInvoice/EmailProFormaInvoice/status/a4caa455-0eed-4c11-
a5a9-2a8333e53db1 HTTP/1.1
Host: 
Accept: application/json
Content-Type: application/json
HTTP/1.1 204 No Content

For doing this using SOAP, please refer to our documentation here. We further document the steps needed for you in the other project scenarios I mentioned at the beginning of this article here.

Postman Starter Kit

Our engineering team has produced a “proof of concept” Postman REST API Requests Collection as a Starter Kit which you can import the JSON file to start using the collection.

Postman is a popular REST client designed to send requests, save responses, add tests, and create workflows. You can download and install the program from here. To lean more about the product and get started, read their blog post entitled, First 5 things to try if you’re new to Postman.

To get started, you first will need to download the Starter Kit’s JSON file by clicking here.  This is a temporary place on OneDrive where you can download the kit before we create a repository on GitHub. Before you start the download, the following screen will come up on your screen:

The Starter Kit collection has the following seven (7) requests:

  1. Login (Post)
  2. Get top Vendors (Get)
  3. Get Vendor with Main Contact (Get)
  4. Create Bill (Put)
  5. Release Bill (Post)
  6. Get Bill (Get)
  7. Logout (Post)

In the screenshot below, you can see that I have imported the JSON code that our engineering team produced in creating the Starter Kit proof of concept.

After installing Postman and downloading our Starter Kit, click on the Import Button from the ribbon below the menu which opens the following Import dialog box.

Click Choose Files and import the JSON file you downloaded to your machine.  After importing the file, you will find the Starter Kit under Collections in Postman as shown in the screenshot above.

Now you are ready to start working with any of the seven requests that we provide you to get started using the REST API in Acumatica.

Summary

To recap, Acumatica latest release 2018 R2 has some nice developer enhancements: increased performance, mobile sitemap definition language (MSDL), reusable business objects, Contract-based API improvements, and new endpoints to support our product’s evolution and latest Acumatica offering – Construction Edition – ProjectProformaInvoiceUnionLocalChangeOrder, etc. that were enumerated in my previous post.

The Pro Forma example scenario illustrates how some of these endpoints can be utilized to send pro formas via email.  This sample scenario can be used with Acumatica 2018 R2 out of the box. It illustrates how easy it is to integrate with external systems.  We have other sample scenarios for the developer to explore as well – managing account groupsrunning project billingstime entry, and GL Transactions.

Also, we have released a proof concept Postman REST API Requests Collection as a Starter Kit which you can import the JSON – a lightweight data-interchange format – and start using it right away.

 


End Notes

¹https://www.investopedia.com/terms/p/proforma.asp

Mark Franks

Platform Evangelist at Acumatica. Mark is responsible for showing people the specifics about what makes Acumatica’s Cloud Development Plaform wonderfully attractive to ISV & Partners. He's also passionate about Running, Latin, and his family.

Categories: Developers, Platform

Subscribe to our bi-weekly newsletter

Compare 10 Leading Cloud Financial Solutions

Using Gartner’s new Magic Quadrant report for cloud core financial solutions, you can easily see what each has to offer—and why Acumatica was named a Visionary.