Country Specific localisation approach review

[Patch]

Manager has the ability to be customised to efficiently address country specific reporting (and perhaps in the future data entry) requirements. Generating such customisation is relatively complex as it involves:-

• A detailed understanding of a particular countries accounting conventions and reporting requirements, not just for a single business but for all businesses Manager’s localisation is going to support (ie the general case).

• Sufficient programming ability to code the accounting requirements into Mangers localisation interface. Again the requirement is for all data users may enter (ie the general case) not just the subset a particular business needs.

• In additions Manager’s localisation interface must also have the breath of program functionality to allow implementation of particular countries reporting and data entry requirements. Such as exposed data fields, transaction aggregation (“or” and “group_by” operators), bar code labelling of invoices, interface to mandated electronic reporting (at what ever level Manger chooses to support) etc.

As a result, generating a country specific localisation, is a more difficult than most other Manger user tasks. In contrast to writing a country specific localisation, once written, Manager then becomes easier for a user to use and meet their accounting requirements in that particular country.

Manager is used in around 200 countries, so the problem is how to generate and maintain localisation for 200 countries. NG Software has the programming skills but acquiring the detailed accounting knowledge required for every country / jurisdiction would not be easy. Generating and supporting all these localisation purely from internal NG Software resources is also likely to require a different pricing structure.

On the other hand, looking a the resources NG Software have invested in creating a country specific localisation interface in about July 2019 and again in Sep 2020 How to implement country-specific report in Manager. As far as I can tell this has resulted in only one community contributed country specific localisation https://github.com/Manager-io/Localizations.json/pulls?q=is%3Apr+is%3Aclosed or perhaps two GST returns have changed / https://github.com/Manager-io/Localizations.json/pull/8

So the question is, among Manager users who seriously would contribute a country specific localisation

• What has stopped you from doing it up to now?

• What is the minimum change required to Manager which would result in you actually contributing a country specific localisation in the future?

[Patch]

Related posts sort of moved as I don’t have forum rights

@lubos

I’m currently experimenting if I can replicate these report transformations using no-coding approach. So rather than writing Liquid markup and HTML, you could define these reports in visual way like custom reports are implemented now.

@Ealfardan

I hope this doesn’t mean we lose the liquid code. Because disabling it would surely reduce possibilities a lot.

[Patch]

@lubos

I’m currently experimenting if I can replicate these report transformations … like custom reports are implemented now.

I think it is an excellent idea to increase the commonality between custom reports and report transformation. Doing so leverages on user learning curve in each Manager facility. However I really don’t know the best way to achieve that.

Clearly as measured by the volume of community report transformation contributed, compared to the work NG Software has contributed to in developing the Country specific localisation interface. We have not leveraged community involvement to achieve any significant increase in country specific localisations over what NG Software would have achieved by just doing the currently community submissions themselves. So there is considerable opportunity for improvement.

To be honest I have found there is a significant barrier to entry in contributing to country specific localisations. The main barriers / time investment prior to useful output has been.

• Lack of clear documentation on what is and is not supported by Managers report transformation interface. The underlying issue is Liquid is an extendable so while there are a variety of online sources which describe how other implementations of Liquid work, reading them only provides hints on how Managers implementation may work. As a result it has basically been necessary to reverse engineer the interface to find out how to use it. A very time consuming task. Trying to reduce this barrier to entry, and help other user avoid wasting their time doing the same, was basically why I wrote Localisation: GST/VAT worksheet programming guide

• Poor error handling and very limited program development tools. Maybe I’m just old school but I find a non declarative language which hides use of undefined procedure calls (filter) and variables results in far more time wasted in debugging than it saves in initial coding. Similarly Managers report transformation environment has rather spartan program development tools.

• Lack of fostering programmer interaction. There is a significant learning curve to using Managers more advanced customisation facilities. This has two consequences. Firstly the functionality is beyond the capabilities of many Manager users, so to ensure they do not get the false impression Manager is hard to use, it is necessary to hide this functionality from them (both in the forum and in the software). Secondly for NG Software to effectively harness the abilities of those who are able use advance software customisation / software coding, the programmers need to efficiently communicate among themselves. I suspect a programming subform, not displayed by default maybe the most efficient way of achieving both requirements simultaneously.

Taking a completely different approach to country specific localisations is an alternative. I can see enhancing the functionality of custom reports type interface will help some Manager users. Enhancing functionality is a two edged sword though, as increasing functionality typically also increases learning curve, so is likely to further decrease the number of users who can actually use custom reports to extract information useful to their business.

A graphical interface can be used to generate code. Doing so works best the more tightly defined the application is (not dis-similar to doing accounts in a spread sheet program vs a basic accounting program, the restrictions introduced by the latter make it easier to do basic accounting). The challenge is, the more general purpose the programming application becomes, the less efficient the restrictions introduced by the graphical interface becomes (both to provide the interface and use the interface).

In summary, I agree making significant changes to the country specific localisation interface is worth examining. I worry that replacing it with a fully graphical interface may not be the most efficient way of achieving the desired outcome. The challenges ahead which most concern me are

• Reduce programmer barrier to entry for country specific localisations
• Data entry screen country specific localisations
• Electronic data interchange consistent with country specific requirements

PS this post was moved from Aust localisation inconsistent with ATO requirements - #6 by Patch

[dalacor]

I don’t know if perhaps you are looking at it from the wrong way around.

I will give you a simple example using the UK.

Here we use VAT, not GST. We use 20% VAT. We use MTD (making tax digital) to file the VAT returns.

Let’s say that there was no localisation report for the UK. Using Manager, I can create any Tax code I want such as 20% rate. There could be a toggle to select VAT or GST within the program and Manager could make it possible to export from the VAT/GST Calculation Worksheet to csv regardless of your country for MTD.

Using the above three examples, you could provide support any country in the world to create correct tax codes, select whether GST/Vat and to enable export of the Calculation Worksheet to a csv file to upload to any software that links up with your tax authority to file GST/VAT returns. Like some countries require you to show the vat inclusive price on invoices and other countries prefer you to show the exclusive vat price on invoices (you can do this by ticking/unticking the relevant box on sales invoice forms).

So the first question I would be asking is how much country specific localisation does one actually need? I think that there is too much focus on creating bespoke templates and less focus on making it possible for Manager uses to modify the templates for their country through the use of tick boxes and toggle options.

With the sole exception of the exact fields on the VAT Calculation Worksheet where I have nine fields, there is nothing different about my business in terms of country from a business in the Netherlands or Australia. Admittedly I don’t have a Business Activity Statement nor do I have a Concept BTW Aangifte Report so I don’t know how different things are and I don’t use payroll.

But would it not be a better idea to allow users to tick/untick/toggle things such as selecting VAT/GST or tax inclusive price, tax exclusive price on sales invoices and apply the same concepts to the calculation worksheets? So instead of designing bespoke country specific forms, the focus could be on ticking options?

Of if this not workable, how about designing VAT and GST templates. For example the VAT Calculation worksheet in the UK could be largely replicated for South Africa as they both use a similar VAT concept and you would just have to remove the EU aspects for South Africa? I just think that there is too much emphasis on designing forms specific to each country, rather than building on the basis that VAT works pretty much the same way in most countries and using that as a template to build on?

[Joe91]

In Ireland we have five VAT rates
Standard rate, Reduced rate, Second reduced Rate, Zero rate and livestock rate

Sometimes these rates are changed temporarily - for example the standard rate was reduced from 23% to 21% for about 7 months in 2020 - this requires another rate

Then we have to distinguish between VAT paid on goods for resale and goods not for resale, on imports and exports to/from EU and non-Eu countries

All in all you would need about 50 different tax codes to cater for all eventualities. I looked at doing a localisation for Ireland but gave up as I felt it would be too complicated for a normal user to select the correct tax code each time

It is true that for most only 10-12 rates would be needed but even coding for those is beyond my attention span and interest.

[dalacor]

It is simpler here in the UK. I only actually use 20% vat and exempt. So I have just disabled the other couple of VAT codes as I need to ask my accountant if I can just simply delete it. I don’t know why you would need 50 codes. When you change the rate, it should apply to new transactions but the older transactions should still be set at the old rate I would have thought? Like when you set prices in inventory, updating the price affects new transactions, but not the old ones.

[Tut]

@dalacor

When you change the rate, it should apply to new transactions but the older transactions should still be set at the old rate I would have thought?

If you edit an existing tax code, all previous transactions that use that rate are modified. If a tax code changes, you need to inactivate the old one and create a new one.

[lubos]

@dalacor

I think that there is too much focus on creating bespoke templates and less focus on making it possible for Manager uses to modify the templates for their country through the use of tick boxes and toggle options.

I agree. I have realized it’s not as important for the country-specific report to have particular look & feel as long as all the figures are present with the right labels.

This is why I’m experimenting how these country-specific reports (not all of them, but at least some) could be constructed with no coding.

[Lance]

I’m seriously looking at experimenting with my country’s GST (Tax) Returns form being localised into Manager.
Working on it slowly.
But I would need some assistance.
.Cheers

[Patch]

@Joe91 and @dalacor thank you for insight into your perspective. I think a variety of view helps know what may or may not be possible.

@Lance

Working on it slowly.
But I would need some assistance.

happy to help, just ask.

@lubos

I’m experimenting how these country-specific reports (not all of them, but at least some) could be constructed with no coding.

For the localisations implemented with coding, showing the control statements in order in the code would really help. At least when using the “Source Code” view. Even if no other support was provided that would enable editing in an external program editor.

Localisations with code are starting to look like “Custom Themes”. Perhaps there is the opportunity for greater commonalty in user interface with time.

[dsherman]

So the question is, among Manager users who seriously would contribute a country specific localisation

• What has stopped you from doing it up to now?
• What is the minimum change required to Manager which would result in you actually contributing a country specific localisation in the future?

I’m the guy who sent the pull request. I’m not an accountant, but I’m an engineer/programmer, doing my own bookkeeping.

I think @Patch’s first question is like asking, “Until now, what has stopped you from jumping into a pool of boiling acid?” People don’t wake up one day, have a cup of coffee, and say, “I think I’ll rewrite the code for my accounting software and then create a pull request.” At least that isn’t what I did. My internal dialogue was more like “AAARRGH!! WTF just happened?? I updated my software and now all my reports are different!!! How can I fix this???”

Nothing stops us from contributing, so long as there’s documentation to show us how to do it, and capable users who are willing to try. But no one contributes until there’s a critical need. The only reason I contributed was because I had to fix something after it broke, and I thought other users might benefit from my effort. Maybe that was the only localization that was broken. (Take that as a compliment.)

For @Patch’s second question, it depends on how the interface will change in the future. With the present system, I think an official Guide would be a good idea. I used Patch’s instructions from his forum post, but there were still a few tricky spots where I needed extra help. Changing the Liquid code was intuitive, but JSON editing was frustrating until I figured it out. So @Patch, if you’re going to keep the localizations.json file, then the documentation for how to modify it could be expanded a bit, and put in a more obvious place.

I hear what @dalacor is suggesting about tick-boxes and drop-downs, but unskilled users could really muck things up. There is an advantage to keeping the localizations somewhat hidden, so users really have to try – and try hard – to break things.

I don’t expect to modify the program ever again, unless another update breaks all my reports again.

I’m a little distraught that program updates can change the contents of reports that have already been filed with our tax authority. What if we get audited? How do we explain that our bookkeeping software doesn’t match what we filed? This adds uncertainty and anxiety about the software.

From an engineering perspective, I can think of a few ways to handle this, each with associated drawbacks:

1. Keep “hard copies” of each report within Manager. This chews up memory, and won’t show HOW the values were generated. Probably not a great option.
2. Embed the Liquid code into each report when it is generated, so subsequent updates don’t change the values. Again, memory intensive. Also, different reports of the same type, generated at different times, would have different code. Again, not a great option.
3. Maintain a code history for each form, so each report can be rolled back to previous versions if required. Perhaps difficult to maintain, especially in the desktop version.

Maybe the update wizard (or maybe Manager itself?) could alert the user when forms change after a software update. That way, we can examine what changed, and verify that everything still works for us. Better yet, would it be possible to run an automated routine that checks each report (with old and new versions of the code) and flag when the two versions don’t match?

Also, if users have modified our localization, we should be able to preserve our modifications.

It’s a remarkable piece of software, and I praise you for your efforts and improvements. But updates shouldn’t break things, ever. As another user mentioned in a different thread, this software isn’t a toy. Businesses – livelihoods – are affected by what you do. Whatever software changes you implement moving forward, please allow us the option to restore things that get left behind.

[dalacor]

@dsherman

I hear what @dalacor is suggesting about tick-boxes and drop-downs, but unskilled users could really muck things up. There is an advantage to keeping the localizations somewhat hidden, so users really have to try – and try hard – to break things.

What I am suggesting would only be for the manager of that business to change. It would be in settings and the expectation is that the manager of that business consult with his accountant to ensure the form is accurate.

[Tut]

@dalacor

the expectation is that the manager of that business consult with his accountant to ensure the form is accurate.

I think that is a forlorn hope. I would never trust my accountant to answer a software question. And just because my accountant confirmed the output of a form is accurate at some point in time, I would have no confidence that meant anything about the utility of the form in the future after program modifications.

[Patch]

@lubos

I’m experimenting how these country-specific reports (not all of them, but at least some) could be constructed with no coding

@lubos You have probably already thought of this and it may not be possible in the Manager development environment but for the No Code option;-

Would it be a cleaner user interface if the user did not enter grid coordinates but instead just clicked on a grid which would then show the definition just for that cell. The grid consisting of an array of buttons. Clicking on one of the grid buttons highlights it and shows that cells definition in detail (above or below the grid of buttons).

• Doing so would de-clutter the display and enable generous screen real estate for each cells definition.

• The cell selection grid could display nothing or a representative part of that cells definition such as the most general or most specific part of the definition.

• The layout may enable more complex features to be added in the future, such as header, footer, line item list. Perhaps an option could be to put the current custom report definition in a full width cell.

[GrahamvdR]

@Patch

So the question is, among Manager users who seriously would contribute a country specific localisation

• What has stopped you from doing it up to now?
• What is the minimum change required to Manager which would result in you actually contributing a country specific localisation in the future?

I did start work on one and was quite excited about getting it done. I have some programming experience, though not in Liquid specifically, and I’m not trained in accounting. I’m not afraid to do a bit of coding, and would tend to prefer this option if it gives more flexibility. I stopped because the lack of documentation meant that I was having to do a lot of guess work and trial and error (made somewhat easier thanks to your guides, @Patch), and even when something appeared to work and give the correct results I didn’t have full confidence in it because I didn’t fully understand what the variables represented and whether I was using them correctly.

In my case there is a good chance I will always need to do a little bit of manual work. For example, if my input VAT exceeds my output VAT I may delay some claims until I can offset them against outputs so I’m not claiming a refund from the tax authority. In the long-term it would be great to have my country-specific reports ready to go, and it would certainly save me time and headaches. But when it has come time to submit my returns I have found it less work to aggregate data from several of Manager’s reports into a spreadsheet and prepare things from there rather than invest the time in creating the new reports. I like to think that I will come back to it one day soon and get it all worked out. A comprehensive guide or reference would really help with this.

Another factor in my delaying it is that it looks like Manager’s approach has continued to evolve, and I don’t want to invest the time in building a report if it’s going to become obsolete with a future update.

[Patch]

@lubos

I just don’t want one report (STP worksheet) to ruin good thing - that is ability to create all report transformation without any coding.

Drill down appears to have been lost with the new Report transformation. I found drill down of reports very useful. It would be great it the removal was only short term.

Also I do wonder if combining the Report transformation edit screen and “Figures” edit screen would further simplify report definition. A possibility would be to

• Split the Report Transformation edit screen into an upper an lower scrollable panels.

• The top panel showing the current Report Transformation edit screen

• When a cell is clicked on in the top panel, the bottom panel showing the current “Figure” edit screen.

• The bottom “Figure” edit screen would need the ability combine (add) the existing “Figure” entries as is currently done in a Report transformation cell definition.

Essentially what is suggested is

• elimination of a user maintained reference (name or coordinate entry) from cell location to cell definition

• and replace it with an software development environment context sensitive cell edit panel.

• creating an interface analogous to a spread sheet with a formula entry bar

[lubos]

@Patch

Drill down appears to have been lost with the new Report transformation. I found drill down of reports very useful. It would be great it the removal was only short term.

I’m working on drill-down. This will be back.