ERPNext customization - add GST # to Sales Invoice

By John Clarke July 3, 2017 ERP No comments yet

Built-in ERPNext 'metadata' modelling tools let users customise their instance to suit.  Quite often, vital enhancements to business data and workflow processes can be quick and easy to self-implement, with no specific end-user skills or IT support staff needed.

This Example Howto:  Add a Custom Field to a DocType
In this example we will add a GST Number to a Company, to list that id on their Sales Invoice.  (Company and Sales Invoice are examples of a DocType, the base data model entity that maps to an SQL table in the database storage.)

Customization tool and method options: Alternative Methods
To implement a given customization task ERPNext offers a choice of tool functions and method alternatives: For example to meet our GST Number requirement, (at least) two different method options exist, that include:

Method A  In module Setup > (Customize) Custom Field 'Company'
Method B  In module Setup > (Customize) DocType 'Company' 

(Note: Whether you choose method A or B, use only one or the other and not both!  While the net result is the same - a field named gst_number is added to the Company DocType - the change you apply will be listed only for the method you use:  For eg the Custom Field List lists only Custom Field changes from method A, but these will not be listed also as a new row in the Company DocType (which would be the case if you had instead used method B); similarly and alternatively, a new row added to Company DocType from method B will not result in a corresponding new Custom Field List entry from A.)

A tip before we start: To navigate ERPNext be sure to use the Awesome search bar, found at the top of the page (except when you are editing something).  As you enter text, the search tool has a prompt list of module or DocType choices to select from. (If ever the search bar 'hangs' simply Reload, see Step 1 below.)

Howto Instruction Steps 1 - 5
Let's begin!  Here we will use strictly method A, so the screenshots show only the Custom Field method that we chose to use. Our GST Number customization takes five steps to implement:

Step 1) add gst_number as Custom Field to Company master

In a New Custom Field instance enter the associated value in these key fields: 
Document='Company' Label='GST Number' Field Type='Data'

Hit Save to write your 'Company-gst_number' changes to the database.

Run Reload to effect your change:  That menu function appears in the drop down from your login ID on the top line.

Step 2) add gst_number as Custom Field to Sales Invoice master

In module Setup > Custom Field, in a New Custom Field instance enter the associated value in these key fields: 
Document='Sales Invoice' Label='GST Number' Field Type='Data'  Depends on='company' and checkmark isMandatory field

The 'Depends on' field specifies the data model link that Sales Invoice depends on Company.

Hit Save to write the 'Sales Invoice-gst_number' changes to the database.

Note:  Enter 'Custom Field List' in the Awesome (search) bar, for a list of our changes saved in Steps 1) and 2) above.

Step 3) With 'source' and 'target' fields specified in steps 1) and 2) above, now specify the code to read and write the value between the two.  

In module Setup > Custom Script 'Sales Invoice-Client'
DocType='Sales Invoice' in Script box enter this code:

cur_frm.add_fetch("company", "gst_number", "gst_number");

The code maps the dependency link of a Sales Invoice target with a Company source, and runs when a New Sales Invoice is created.

Step 4) Next, go to the Company instance to set the GST Number field with the required identifier value.

Now run some sanity checks to confirm the expected GST Number id value is stored in the database.

Query the database from a ERPNext root user console:
bench mysql
select gst_number from tabCompany;

MariaDB [d56cb677eaab3383]> select gst_number from tabCompany;
| gst_number        |
| 12345 6789 RT0001 |
1 row in set (0.01 sec)

MariaDB [d56cb677eaab3383]> select gst_number from `tabSales Invoice`;
| gst_number        |
| 12345 6789 RT0001 |
1 row in set (0.00 sec)

Query the database from a ERPNext root user console:
bench console
In [5]: frappe.get_all('Company', fields=['name', 'gst_number'])
Out[5]: [{'gst_number': u'12345 6789 RT0001', 'name': u'Wallabee Consulting Inc'}]

Step 5) Create a test Sales Invoice and confirm that the GST Number appears there. We're now done.


ERPNext offers other alternative ways to implement this use case:  For example create a Print Format to 'hard code' embed the GST Number identifier value in a Sales Invoice . In the (non-Standard) Print Format case, that value would not be stored in the database, this method was taken as an exercise example.

This example customization uses a Custom Script that are executed only on the client-side (i.e. in Forms).  Since all such client-side customizations are stored in the database itself, these changes are transparent and not affected by code 'updates' that apply on the server that are a separate case and often require developer intervention to manually merge update code with customization changes.


For more examples refer to the ERPNext documentation manual

and the help forum

No comments yet

No comments yet. Start a new discussion.

Add Comment