Wednesday, 24 August 2016

Configuring Batch Payments for Custom File Format

Hi All,

Today I want to share with you an configuration way for new bank format. Out of the box Acumatica supports: ACH and GIRO file types.

Support for bank files works through configuration of 3 different components

  1. Batch Payments - Process where multiple payments can be combined to one single document. Exactly this document will be exported to payment file.
  2. Export scenarios - To generate real file from document Acumatica uses export scenarios with special data provider. Scenario is uses as instruction and columns mapping between file and acumatica.
  3. Data Provider - Knows how to generate required file. For different payment standard you may need to create a different providers, but luckily it is highly customization.

Lets start with Batch Payments.
You can setup special payment method that will be configured as "batch payment".

Later you can generate Batch payment document that will combine one or several payments into one batch (Screen ID: AP305000)

If you click "Export" button on this screen, system will generate file and attach it to the current document. But the actual export will be done with export scenario, that you configure for Payment Method on previous image. Here you can see an export scenario that you can copy and customize for your own format.
As I already mention, scenarios are mostly mapping between Acumatica Batch Payment document and file format. You selecting Acumatica and File fields and sometimes can just change some fields using formulas and other data manipulations.

Now we are coming to Provider configuration. Each provider consists of 2 main parts: parameters and fields configuration. Parameters is mostly responsible on some small configurations of the result data format. Sometimes when it is complex to change configuration with single property, you can decide to create own provider.
In Acumatica we have 2 out of the box providers:

  1. ACH Provider - mostly responsible for generation fix-width file format. Also it may be used for files with strict requirements for block size.
  2. GIRO Provider - mostly responsible for generation flexible and less structured file with no limitations on block or line sizes.

File format is defined by schema file, which is a simple text file attached to provider.

Schema file contains:

  • Header/footer information. This is #01 number on the begin of line. Number defines the level of sub group. #01 - is header and footer, #02 can be a group of documents, #03 can be details. For the GIRO provider usually it is enough to have only 2 levels
  • Placeholders for dynamic fields from Acumatica - values like this {H2_Corporate_ID:30}. This field will be visible in Acumatica Export scenario and can be mapped with data. Fields can contain some formation options:
    • ":30" - means that field should be not more that 30 characters in length.
    • ":-10" - means that field value should aligned to right
    • "NotKey|FillOnEnd" - define calculation parameters, like in the reports.
      • NotKey - means that field should not define new group when field is changed
      • FillOnEnd - means that data should be calculated in the end
    • "=TotalCount" - some formulas that can do simple calculations
  • Simple text, that will me stored as is. In my example all character like this "|||||||||||||||" means just a simple text, that should be there in the end file. Of course there are some parameters that can be passed there, but in our continuations it can be empty.

There are some more parameters that can be used when required, but i think it is enough for overview.

You also can create a new provider and inherit it from the base one. For example i'm providing here some simple provide that add new functionality for calculation running total:

public class MyGIROProvider : GIROPaymentProvider
       public override string ProviderName
              get return "MyGIROProvider"; }

       private decimal RunningTotal;
       public decimal AppendToTotal(decimal aAmount)
              this.RunningTotal += aAmount;
              return this.RunningTotal;


This function (AppendToTotal) we actually can use from Export scenarios.

Also you may note some yellow warnings on Source Objects. This means that we are using Data View that exists in Graph object, but does not exists in the UI, so it is some sort of hidden view. It is totally OK for this scenario and sometimes may be useful for you as well.
The good think for you to know Acumatica Platform and Customization tools - it may help you a lot if you want to define new provider.

This is the actual payment file result of new reconfigured provider:

Have a nice configuration!

No comments: