Difference between revisions of "Account Hierarchy Template"

From GnuCash
Jump to: navigation, search
(A sample script for big templates)
m (A sample script for big templates: typo)
 
(83 intermediate revisions by 12 users not shown)
Line 1: Line 1:
=Creating localized Account Hierarchy Templates=
+
Creating localized Account Hierarchy Templates.
 +
:[{{URL:GH}}Gnucash/gnucash/tree/stable/data/accounts Directory of currently shipped templates]
  
== Motivation ==
+
[[Category:L10N]][[Category:Account Hierarchy Template]][[Category:De/Kontenrahmen|Kontenrahmen]]
  
Sometimes the standard GnuCash account hierarchy template needs a bigger rework before it fits the requirements of your government - special for business purposes. In this case it might be better, to start from scratch.
+
== Motivation and Overview ==
  
== An almost normal Start ==
+
Sometimes the standard GnuCash account hierarchy template needs a bigger rework before it fits the requirements of your government - especially for business purposes. In this case it might be better to start by creating a new hierarchy template from scratch.
Start with an new empty file. Create the account hierarchy, which according your needs.
 
  
FIXME: I am quite not shure, if save file or export hierarchy is the better choice now. One obvisious difference: export saves no transactions, but also other parts will be ignored. E.g. what will happen with taxtables?
+
Depending on your experience and resources there are different approaches:
 +
* ''Use GnuCash'' to create a new or adjust an outdated template:  [[#Create an Example File]]
 +
: and do some ''Copy&Paste'' [[#Adjust the Header]] [[#... and the Footer]] with your preferred text editor.
 +
:* If you already have a working file, you want to remove personal data: [[#Strip data from an existing, uncompressed gnucash xml file]]
 +
* With some ''XML knowledge'' it might be faster to use a text editor to adjust an existing template: [[#Strip data from an existing, uncompressed gnucash xml file]].
 +
* With some ''programming knowledge'' adjust [[#A_sample_script_for_big_templates]] to generate an account template from a formatted text file of your standard.
 +
;Conventions: Do not use the colon <code>:</code> in account names. It is by default used as account separator symbol.
 +
: Mark accounts, which contain subaccounts as <tt>placeholder</tt>.
 +
: Do not prefix the account name with the <tt>account number</tt>. There is a separate field for them.
 +
: Try to keep the account names short. You can put more details in the <tt>description</tt> and <tt>notes</tt> fields.
  
== Changing the Header ==
+
;Important: In all cases you want to run the [[#Syntax Check]] before sharing your file.
  
After you saved your template, you must manually adjust the header of your new created file, otherwise the druid does not know, how to handle your template.  
+
== Create an Example File ==
 +
Usually you will start with an empty file or a similar - e.g. an older version - template, but it is also possible to strip down the copy of a working gnucash file.
  
<pre>
+
=== Start with an new empty gnucash file ===
 +
#After starting gnucash in the Chart of accounts (CoA) —usually in a tab named <tt>Accounts</tt>— enable useful columns, see the [{{URL:docs:manual|de}}gui-acct-tree.html#idm45742311582656 images currently only in the german Manual]:
 +
#;List of useful columns and their xml tags:
 +
#:;Account Name: required: '''<act:name>'''
 +
#:;Type: required: '''<act:type>'''
 +
#:;Account Code: alphanumerical Account Number, optional, allows a different order than alphabetical by name: '''<act:code>'''
 +
#:;Description: optional, if account name needs explanations: '''<act:description>'''
 +
#:;Notes: optional, e.g. instructions for the user: '''<slot:key>notes</slot:key>'''
 +
#:;Tax info: optional, currently only in DE and US of interest: '''<slot:key>tax-related</slot:key>'''
 +
#:;Hidden: optional, you shouldn't use it, but the user can hide currently unused accounts later
 +
#:;Placeholder: optional, write protection for group headers: '''<slot:key>placeholder</slot:key>'''
 +
#::They will also not appear in the dropdown list so select accounts.
 +
#:;Opening Balance: You need ''exactly one account'' with this flag in the whole resulting file. That is not easily to verify for a modular template. It will be the counter account when users add a opening balance using the assistant: <syntaxhighlight lang="xml"><slot:key>equity-type</slot:key>
 +
<slot:value type="string">opening-balance</slot:value>
 +
</syntaxhighlight>
 +
#:;Account Color: optional, don't use it! It is a question of personal taste and capabilities.
 +
# Create the account hierarchy, which is according your needs.
 +
# Usually you should mark accounts which have subaccounts as ''Placeholder''.
 +
# Before you save to file in xml format, uncheck <tt>Edit->Preferences->General->Files:Compress Files</tt> to get an uncompressed xml file.
 +
 
 +
FIXME: I am not quite sure whether "Save file" or "Export hierarchy" is the better choice currently. One obvious difference: export saves no transactions, but also other parts will be ignored.
 +
(E.g. what will happen with taxtables, but it seems only accounts can be created.)
 +
 
 +
=== Strip data from an existing, uncompressed gnucash xml file ===
 +
You have a nice working GnuCash file and somebody asks for a copy of your template. So you want to ''remove'' all your '''personal data'''. But you surely want to ''keep'' the '''accounts''' and in ''business'' templates the '''tax table'''.
 +
 
 +
Open the copy of the file with a text editor, preferably one that provides syntax highlighting for xml. Remove unwanted sections:
 +
<syntaxhighlight lang="xml">
 +
<book:slots> ... </book:slots>
 +
<gnc:count-data ...>        <!-- give you an overview, and should be adjusted at the end -->
 +
<gnc:commodity version="2.0.0">...</gnc:commodity>  <!-- remove only foreign currencies -->
 +
<gnc:transaction version="2.0.0">...</gnc:transaction>
 +
<gnc:budget version="2.0.0">...</gnc:budget>
 +
<gnc:GncCustomer version="2.0.0">...</gnc:GncCustomer>
 +
<gnc:GncEntry version="2.0.0">...</gnc:GncEntry>
 +
<gnc:GncInvoice version="2.0.0">...</gnc:GncInvoice>
 +
<gnc:GncVendor version="2.0.0">...</gnc:GncVendor>
 +
<!-- feel free to add that which I missed like employee, price, order... -->
 +
</syntaxhighlight>
 +
 
 +
Now run a [[#Syntax Check]].
 +
 
 +
== Convert the Example into a Template ==
 +
 
 +
=== Extensible Stylesheet Language Transformations ===
 +
XSLT is a powerful language for converting XML files into other formats. GnuCash has several XSL files in [{{URL:GH}}Gnucash/gnucash/tree/stable/contrib/xslt contrib/xslt]. Unfortunately the contrib directory is currently not part of the installation. The XSLs can be processed by the program <code>xsltproc</code>, which is part of a package '''libxslt-tools''' or similar.
 +
Example for a compressed file:
 +
<Syntaxhighlight lang="sh">
 +
gunzip -c <your gnucash file> | \
 +
      xsltproc --stringparam title "Spacecraft project" \
 +
                --stringparam short-description "Accounts useful for space exploration" \
 +
                --stringparam long-description "A set of accounts useful for space exploration. Implements NASA Standards FOO-1234-BAR and FOO-3456-BAZ for Earth Orbit Satellites, Earth Orbit Space Stations, Solar System Manned and Unmanned Spaceflight, and Interstellar Exploration." \
 +
                gnc2xea.xsl -
 +
</Syntaxhighlight>
 +
*For uncompressed files start from line 2 and replace the last <code>-</code> by your filename.
 +
*''gnc-act:exclude-from-select-all'' (see below) will be set.
 +
* Because there was a change after the xsl was written, you still need to change [[#... the Body ...]].
 +
 
 +
See gnc2xea.xsl in [{{URL:GH}}Gnucash/gnucash/tree/stable/contrib/xslt/README xslt README].
 +
 
 +
=== Manually ===
 +
In case xsltproc fails, you want some adjustments or you want to understand the differences read this section.
 +
==== Adjust the Header ====
 +
 
 +
After you have saved your template, you must manually adjust the first lines (the "header") of your newly created file as follows. Otherwise the "New File Wizard" will not know how to handle your template. The file name itself does not matter (it will not be visible anywhere), but the first lines of the file must contain the following information:
 +
 
 +
<syntaxhighlight lang="xml" line highlight="1,2,34,37,40,43,45">
 
<?xml version="1.0" encoding="utf-8" ?>
 
<?xml version="1.0" encoding="utf-8" ?>
 
<gnc-account-example  
 
<gnc-account-example  
Line 32: Line 108:
 
   xmlns:fs="http://www.gnucash.org/XML/fs"
 
   xmlns:fs="http://www.gnucash.org/XML/fs"
 
   xmlns:gnc="http://www.gnucash.org/XML/gnc"
 
   xmlns:gnc="http://www.gnucash.org/XML/gnc"
 +
  xmlns:gnc-act="http://www.gnucash.org/XML/gnc-act"
 
   xmlns:invoice="http://www.gnucash.org/XML/invoice"
 
   xmlns:invoice="http://www.gnucash.org/XML/invoice"
 
   xmlns:job="http://www.gnucash.org/XML/job"
 
   xmlns:job="http://www.gnucash.org/XML/job"
Line 51: Line 128:
 
</gnc-act:title>
 
</gnc-act:title>
 
<gnc-act:short-description>
 
<gnc-act:short-description>
   Inter Galactical Accounting Standard, Stardate 2099
+
   Intergalactic Accounting Standard, Stardate 2099
 
</gnc-act:short-description>
 
</gnc-act:short-description>
 
<gnc-act:long-description>
 
<gnc-act:long-description>
   This is the Base Module of the Inter Galactical Accounting Standard as transmitted on stardate 2099-01-01. You might also need the module "starfleet" or "klingon". ~Cpt. Picard
+
   This is the Base Module of the Intergalactic Accounting Standard as transmitted on stardate 2099-01-01. You might also need the module "starfleet" or "klingon". ~Cpt. Picard
 
</gnc-act:long-description>
 
</gnc-act:long-description>
 
<gnc-act:exclude-from-select-all>1</gnc-act:exclude-from-select-all>
 
<gnc-act:exclude-from-select-all>1</gnc-act:exclude-from-select-all>
Line 63: Line 140:
 
   <act:commodity-scu>0</act:commodity-scu>
 
   <act:commodity-scu>0</act:commodity-scu>
 
</gnc:account>
 
</gnc:account>
</pre>
+
</syntaxhighlight>
  
 
Annotations:
 
Annotations:
 
* Line 1: encoding
 
* Line 1: encoding
: You must save your file in the appropriate encoding.
+
: You must save your file in the appropriate '''character encoding''' and note the used character encoding here! For possible values, see [[Locale Settings]].
 
* Line 2ff: Namespace
 
* Line 2ff: Namespace
 
: The parser in GC 2.2.x makes no use of it, but future versions might change.  
 
: The parser in GC 2.2.x makes no use of it, but future versions might change.  
: Some details can be found in [http://lists.gnucash.org/logs/2009/01/2009-01-22.html#T00:44:42] or in the [http://svn.gnucash.org/repo/gnucash/trunk/src/doc/xml/gnucash-v2.rnc source docs]
+
: Some details can be found in [{{URL:Lists}}logs/2009/01/2009-01-22.html#T00:44:42] or in [{{URL:GH}}Gnucash/gnucash/blob/stable/libgnucash/doc/xml/gnucash-v2.rnc gnucash-v2.rnc]. Defining the namespace has the benefit, you can check the syntax of your file later with <code>xmllint</code>.
 
* gnc-act:title
 
* gnc-act:title
: Enter a short, unique Name, which is usually also part of his filename,
+
: Enter a short, unique Name, which is shown in the table in the "New File Wizard" so that the user can choose this template. This name is usually also part of the filename, but the file name itself does not matter and is never shown to the user. This name is restricted to ONE line.
 
* gnc-act:short-description
 
* gnc-act:short-description
: A one line description shown in the selection box
+
: A one-line description shown in the table in the "New File Wizard"
 
* gnc-act:long-description
 
* gnc-act:long-description
: Everything, the user should know about the template.
+
: A somewhat longer description which is shown in a text box in the "New File Wizard" if the user selects this template. This should explain the content and the efficient usage of the template to the user.
 +
: A nice example for the descriptions is in [{{GitURL}}/gnucash/blob/7853f5a24a4ed6e5cf32fdf6e5eba217a1e312cd/data/accounts/de_DE/acctchrt_wohnungsw.gnucash-xea#L35 accounts/de_DE/acctchrt_wohnungsw.gnucash-xea], which Google translates to:<syntaxhighlight lang="xml"><gnc-act:title>Housing Accounts Framework </gnc-act:title>
 +
<gnc-act:short-description>Chart of Accounts for the Real Estate Industry (as of 2012) </gnc-act:short-description>
 +
<gnc-act:long-description>Chart of accounts for the housing industry according to GdW / Hammonia Verlag (now Haufe), as of 2012
 +
Usage notes: https://wiki.gnucash.org/wiki/De/Wohnungswirtschaft
 +
Creator: Christoph Franzen, christoph@(censored).de
 +
</gnc-act:long-description></syntaxhighlight>
 +
:Note the link to the wiki with more details!
 
* gnc-act:exclude-from-select-all
 
* gnc-act:exclude-from-select-all
: As your template should usually not be mixed with the private oriented templates, set this flag.
+
: Indicates whether this template should be selected if the user clicks the button "Select All". The business-related templates are probably rather special and should not be mixed with a general home-user account structure, so you should probably enable this flag by writing a "1" in here.
 
* Root Account
 
* Root Account
: Only the base module should have exactly one.  
+
: Only the base module should have exactly one.
: The accounts in the optional modules linked over <act:parent type="guid">...</act:parent>
+
: Because it is only used internally, do not translate it!
 +
: The accounts in the optional modules linked over <act:parent type="new">...</act:parent>
 +
 
 +
If you decide to copy&paste this template, please '''replace the root guid by a self generated''' with
 +
* either:
 +
:<Syntaxhighlight lang="sh">
 +
uuidgen | sed -e 's/-//g'
 +
</Syntaxhighlight>
 +
: (Dependencies: '''uuidgen''' is part of ''util-linux'' and '''sed''' has its own package)
 +
* or use an online uuid generator like [https://www.guidgenerator.com/ this one] (any other one will do as well). Be sure to untick "Hyphens" to generate gnucash compatible guids. If you forget to untick it, or you use a site that doesn't offer this option, simply remove the hyphens yourself.
 +
.
 +
 
 +
==== ... the Body ... ====
 +
Note how the account hierarchy is defined by each account having a "globally unique identifier" (guid) as the value of its act:id element. E.g 5df07084fb48f599732df308a71d8246 in the case of the root account. Any child account refers back to its parent by having the parent's guid as the value of its act:parent element.
 +
 
 +
<syntaxhighlight lang="xml" line highlight="3,8,15">
 +
<gnc:account version="2.0.0">
 +
  <act:name>Root Account</act:name>
 +
  <act:id type="guid">5df07084fb48f599732df308a71d8246</act:id>
 +
  <act:type>ROOT</act:type>
 +
</gnc:account>
 +
<gnc:account version="2.0.0">
 +
  <act:name>Child account</act:name>
 +
  <act:id type="guid">03a869e21f475e8e7a0688e32035ee9a</act:id>
 +
  <act:type>ASSET</act:type>
 +
  <act:commodity>
 +
    <cmdty:space>ISO4217</cmdty:space>
 +
    <cmdty:id>SEK</cmdty:id>
 +
  </act:commodity>
 +
  <act:commodity-scu>100</act:commodity-scu>
 +
  <act:parent type="guid">5df07084fb48f599732df308a71d8246</act:parent>
 +
</gnc:account>
 +
</syntaxhighlight>
 +
 
 +
When GnuCash creates a new file (book) based on an account hierarchy template, these guids should be replaced by new ones, to ensure there are no collisions, for example if several templates are combined when creating the book. Therefore you should change the value of the type attribute for the act:id and act:parent elements like this, as an indication that new guids should be generated:
 +
 
 +
<Syntaxhighlight lang="xml"><act:id type="guid"> / <act:parent type="guid"></Syntaxhighlight> -->
 +
<Syntaxhighlight lang="xml"><act:id type="new"> / <act:parent type="new"></Syntaxhighlight> respectively.
 +
 
 +
Make sure you leave the actual guids intact, as the parent-child relations would otherwise break.
 +
 
 +
From 2.6.2 commit [{{URL:GH}Gnucash/gnucash/commit/1e303f5d211fa41 Replace type="guid" with type="new" in gnucash-xea files]: Having type="guid" causes the accounts created from the file to use the example GUID instead of generating a new one.
 +
 
 +
And if you used the XSLT, replace all occurrences of
 +
<Syntaxhighlight lang="xml"><slot xmlns=""></Syntaxhighlight> by
 +
<Syntaxhighlight lang="xml"><slot></Syntaxhighlight>.
 +
From [{{URL:Bugs}}show_bug.cgi?id=795237#c19 Comment 19 of Update of "wohnungsw" template].
 +
 
 +
This is an sample shell script doing the conversion and replacing the above mentioned parts after that:
 +
<Syntaxhighlight lang="sh">
 +
#!/bin/sh
 +
BAK=`date +%Y%j%H%M%S`
 +
for D in $@
 +
do
 +
KRXEA="$D.xea"
 +
if [ "$D" = "KRI" ]
 +
then
 +
  KRXAC="$D.xac.gz"
 +
  TITLE="Kontenrahmen für die Wohnungswirtschaft"
 +
  SHORT="Kontenrahmen für die Immobilienwirtschaft (Stand 2012)"
 +
  LONG="Kontenrahmen für die Wohnungswirtschaft nach GdW / Hammonia Verlag (jetzt Haufe), Stand 2012
 +
Hinweise zur Verwendung: https://wiki.gnucash.org/wiki/De/Wohnungswirtschaft
 +
Ersteller: Christoph Franzen, christoph@alte-pflasterei.de"
 +
elif [ "$D" = "SKR49" ]
 +
then
 +
  KRXAC="$D.gnucash"
 +
  TITLE="Kontenrahmen SKR49 für Vereine, Stiftungen, gGmbHs"
 +
  SHORT="Datev-Kontenrahmen SKR49 für Vereine, Stiftungen und gemeinnützige GmbHs"
 +
  LONG="Ein Kontenrahmen für Vereine nach dem SKR49 der Datev
 +
 
 +
Bei Gebrauch dieses Kontenrahmens sind die allgemeinen Konten abzuwählen.
 +
An dem Rahmen sind selbstverständlich noch Anpassungen erforderlich,
 +
bis man den seinen Bedürfnissen entsprechenden Kontenplan hat.
 +
Hinweise zur Verwendung: https://wiki.gnucash.org/wiki/De/SKR49
  
If you decide, to copy&paste this template, please replace the root guid by a self generated.
+
Ersteller: Michael Braun 2009, michael-developer@fami-braun.de
 +
Formalia für GnuCash-Vorlagen: Frank H. Ellenberger 2009
 +
Erweitert auf den Stand 2018: Christoph Franzen 2017-2018, christoph@alte-pflasterei.de"
 +
else
 +
  exit
 +
fi
 +
done
 +
mv "$KRXEA.gz" "$KRXEA.$BAK.gz"
 +
gunzip -c $KRXAC | xsltproc --stringparam title "$TITLE" --stringparam short-description "$SHORT" --stringparam long-description "$LONG" gnc2xea.xsl - | sed -e "s/act:id type=\"guid/act:id type=\"new/g" > "$KRXEA.tmp"
 +
sed -e "s/slot xmlns=\"\"/slot/g" < "$KRXEA.tmp" > "$KRXEA"
 +
gzip -N9 "$KRXEA"
 +
</Syntaxhighlight>
 +
 
 +
==== ... and the Footer ====
 +
 
 +
Close to the end of the file, you should replace
 +
<Syntaxhighlight lang="xml"></gnc-v2></Syntaxhighlight>
 +
by
 +
<Syntaxhighlight lang="xml"></gnc-account-example></Syntaxhighlight>
 +
.
 +
 
 +
== Clean up ==
 +
Depending on the way you created the template, there can be some redundant elements in your template. If you are unsure, you can ask the maintainers to do this part for you.
 +
 
 +
=== Unwanted Elements ===
 +
;Slots
 +
:Information about Online Banking is different for each person. Example FinTS/HBCI: <syntaxhighlight lang="xml">
 +
    <slot>
 +
      <slot:key>hbci</slot:key>
 +
      <slot:value type="frame"/>
 +
    :
 +
    </slot>
 +
</syntaxhighlight>
 +
:Account Colors are a question of personal taste: <syntaxhighlight lang="xml">
 +
    <slot>
 +
      <slot:key>color</slot:key>
 +
      <slot:value type="string">...</slot:value>
 +
    </slot>
 +
</syntaxhighlight>
 +
 
 +
=== Elements with Default Values ===
 +
;Slots
 +
:Empty notes: <syntaxhighlight lang="xml">
 +
    <slot>
 +
      <slot:key>notes</slot:key>
 +
      <slot:value type="string"></slot:value>
 +
    </slot>
 +
</syntaxhighlight>
 +
:Unset Placeholder flags: <syntaxhighlight lang="xml">
 +
    <slot>
 +
      <slot:key>placeholder</slot:key>
 +
      <slot:value type="string">false</slot:value>
 +
    </slot>
 +
</syntaxhighlight>
 +
;Account Elements
 +
:Finally, if you removed slots, you can end with an empty slots element in some accounts: <syntaxhighlight lang="xml">
 +
  <act:slots>
 +
  </act:slots>
 +
</syntaxhighlight>
 +
:If you find them, you can remove them.
 +
 
 +
== Testing ==
 +
From time to time you should check the syntax and finally by using your file in GnuCash.
 +
 
 +
=== Syntax Check ===
 +
Finally you should run
 +
<!-- Fixme: --valid fails: no DTD found !
 +
    xmlns:vendor="http://www.gnucash.org/XML/vendor">
 +
-->
 +
:;for one file: <SyntaxHighlight lang="sh">
 +
xmllint --noout <mytemplate>
 +
</SyntaxHighlight>
 +
:; or multiple files: <SyntaxHighlight lang="sh">
 +
for i in *-xea; do echo $i; xmllint --noout $i; done
 +
</SyntaxHighlight>
 +
to verify the syntactical correctness (std well-formed check) of your file. No output means that no errors were found.
 +
 
 +
If xmllint is missing on your computer see [[Translation#Prerequisite]].
 +
 
 +
=== Testing in Gnucash ===
 +
* If you have the sources and are able to build and install GnuCash from them then make your changes in the source directory and build and install GnuCash as usual.
 +
* If not, you want to modify GnuCash installed by a package manager, the Microsoft Windows GnuCash Installer, or a macOS application bundle, locate the installed templates directory:
 +
** Linux/BSD distribution package manager: <code>/usr/share/gnucash/accounts</code>. You'll need <code>root</code> privs to write to this directory.
 +
** macOS application bundle: <code>Gnucash.app/Contents/Resources/share/gnucash/accounts</code>
 +
** macOS package manager: <code>share/gnucash/accounts</code> in the package manager's installation directory, <code>/opt/local</code> is the default for MacPorts and <code>/usr/local/Cellar</code> is the default for Homebrew.
 +
** Microsoft Windows installer: <code>C:\Program Files (x86)\gnucash\share\gnucash\accounts</code>. You'll need to use a CMD or Powershell window running as administrator to write to this directory.
 +
 
 +
# <syntaxhighlight lang="sh">gnucash --nofile</syntaxhighlight>
 +
# <tt>File->New File</tt>
 +
# go to Step 4—<tt>Choose accounts to create</tt> and select either for
 +
#;personal templates: <code>Select All</code> or
 +
#;business templates: <code>Clear All</code> and manually select your template
 +
# Step 5—<tt>Setup selected accounts</tt> verify that
 +
## ''each account with a triangle'' on the left is marked as '''placeholder''' on the right side and
 +
## you can enter an <tt>Opening Balance</tt> for at least one leaf account of your <tt>Assets</tt> branch.
 +
##: If that fails, your template is missing exactly one account usually  named <tt>Opening Balance</tt> in  your <tt>Equity</tt> branch with a slot <syntaxhighlight lang="xml">
 +
    <slot>
 +
      <slot:key>equity-type</slot:key>
 +
      <slot:value type="string">opening-balance</slot:value>
 +
    </slot>
 +
</syntaxhighlight>
  
 
== A sample script for big templates ==
 
== A sample script for big templates ==
  
If the template is really big - as the german - and you have it as text file, it might be less work, to adjust the following script from [http://bugzilla.gnome.org/show_bug.cgi?id=568653], to create the gnucash template.
+
If the template is really big - as the german one - and you have it as a text file, it might be less work to adjust the following script from [{{URL:Bugs}}show_bug.cgi?id=568653] to create the gnucash template. There are tools available on the internet and probably on your computer to convert often used formats such as PDF to plain text files e.g. [{{URL:wp}}pdftotext pdftotext].
  
<pre>
+
<syntaxhighlight lang="bash">
 
#! /bin/bash
 
#! /bin/bash
  
# This applications takes an text input file $FILE
+
# This application takes a text input file $FILE
 
# and converts it into a gnucash account scheme with a random name.
 
# and converts it into a gnucash account scheme with a random name.
 
# The input file is read line by line where each line
 
# The input file is read line by line where each line
Line 136: Line 393:
 
echo "start"
 
echo "start"
  
FILE="Art.-Nr.11180.txt"
+
FILE="<source>.txt"
  
 
if [ ! -f "$FILE" ]; then  
 
if [ ! -f "$FILE" ]; then  
Line 159: Line 416:
 
cat >> "$OUT" <<EOF
 
cat >> "$OUT" <<EOF
 
<?xml version="1.0" encoding="utf-8" ?>
 
<?xml version="1.0" encoding="utf-8" ?>
<gnc-v2
+
<gnc-account-example
 
     xmlns:gnc="http://www.gnucash.org/XML/gnc"
 
     xmlns:gnc="http://www.gnucash.org/XML/gnc"
 +
    xmlns:gnc-act="http://www.gnucash.org/XML/gnc-act"
 
     xmlns:act="http://www.gnucash.org/XML/act"
 
     xmlns:act="http://www.gnucash.org/XML/act"
 
     xmlns:book="http://www.gnucash.org/XML/book"
 
     xmlns:book="http://www.gnucash.org/XML/book"
Line 192: Line 450:
 
<gnc:account version="2.0.0">
 
<gnc:account version="2.0.0">
 
   <act:name>Root Account</act:name>
 
   <act:name>Root Account</act:name>
   <act:id type="guid">$ROOT</act:id>
+
   <act:id type="new">$ROOT</act:id>
 
   <act:type>ROOT</act:type>
 
   <act:type>ROOT</act:type>
 
   <act:commodity-scu>0</act:commodity-scu>
 
   <act:commodity-scu>0</act:commodity-scu>
Line 207: Line 465:
 
<gnc:account version="2.0.0">
 
<gnc:account version="2.0.0">
 
   <act:name>Kontenklasse $LAST</act:name>
 
   <act:name>Kontenklasse $LAST</act:name>
   <act:id type="guid">$CURR</act:id>
+
   <act:id type="new">$CURR</act:id>
 
   <act:type>ASSET</act:type>
 
   <act:type>ASSET</act:type>
 
   <act:commodity>
 
   <act:commodity>
Line 221: Line 479:
 
     </slot>
 
     </slot>
 
   </act:slots>
 
   </act:slots>
   <act:parent type="guid">$ROOT</act:parent>
+
   <act:parent type="new">$ROOT</act:parent>
 
</gnc:account>
 
</gnc:account>
 
EOF
 
EOF
Line 235: Line 493:
 
<gnc:account version="2.0.0">
 
<gnc:account version="2.0.0">
 
   <act:name>$ID $1</act:name>
 
   <act:name>$ID $1</act:name>
   <act:id type="guid">$CURRSUB</act:id>
+
   <act:id type="new">$CURRSUB</act:id>
 
   <act:type>ASSET</act:type>
 
   <act:type>ASSET</act:type>
 
   <act:commodity>
 
   <act:commodity>
Line 249: Line 507:
 
     </slot>
 
     </slot>
 
   </act:slots>
 
   </act:slots>
   <act:parent type="guid">$CURR</act:parent>
+
   <act:parent type="new">$CURR</act:parent>
 
</gnc:account>
 
</gnc:account>
 
EOF
 
EOF
Line 259: Line 517:
 
<gnc:account version="2.0.0">
 
<gnc:account version="2.0.0">
 
   <act:name>$1 $2</act:name>
 
   <act:name>$1 $2</act:name>
   <act:id type="guid">$(getuid)</act:id>
+
   <act:id type="new">$(getuid)</act:id>
 
   <act:type>ASSET</act:type>
 
   <act:type>ASSET</act:type>
 
   <act:commodity>
 
   <act:commodity>
Line 268: Line 526:
 
   <act:description>$2</act:description>
 
   <act:description>$2</act:description>
 
   <act:code>$1</act:code>
 
   <act:code>$1</act:code>
   <act:parent type="guid">$CURRSUB</act:parent>
+
   <act:parent type="new">$CURRSUB</act:parent>
 
</gnc:account>
 
</gnc:account>
 
EOF
 
EOF
Line 306: Line 564:
 
done < "$FILE"
 
done < "$FILE"
  
echo "</gnc-v2>" >> "$OUT";
+
echo "</gnc-account-example>" >> "$OUT";
 
echo "done: written to $OUT"
 
echo "done: written to $OUT"
</pre>
+
</syntaxhighlight>
 +
 
 +
=== Annotations ===
 +
There are a few terms in the script, you might wish to adjust or at least understand:
 +
* Kontenklasse: account class, first level in the account hierarchy.
 +
* kontengruppe: account group, lower node in the tree, but not a leaf.
 +
: Both above are placeholders.
 +
* Konto: account.
 +
* Erträge: earnings.
 +
* <cmdty:id>: 3-letter ISO-currency symbol.
 +
* <act:commodity-scu>: smallest currency unit, in most cases 100 ''{C/S}en[t]*''|''P[f]en*'' or whatever.
 +
Eventually you wish the account code $1 only in <act:code> and not in <act:name>.
 +
 
 +
== Exporting an existing account hierarchy ==
 +
 
 +
You can create an account hierarchy template using this method.
 +
 
 +
* You already have a account hierarchy in a gnucash file, but you want to export a subset
 +
* Go to file > export > export the xml
 +
* Select the subset you want from the xml as a starting point
 +
* Change the file xml structure according to the rules defined on this page
 +
* Take care when you change the xml file: ids and other information may conflict with your current account hierarchy
 +
* Put the xml file you edit in /usr/share/gnucash/your_language/yourfilename.gnucash-xea
 +
* Restart Gnucash
 +
* Use the New Account Hierarchy wizard to import your new account hierarchy 
 +
 
 +
[[Translation#How_to_translate_the_files_containing_the_new_account_hierarchies | Back to Translation]]
 
----
 
----
[[Translation#How_to_translate_the_files_containing_the_new_account_hierarchies | Back to Translation]]
+
== Future Development ==
 +
This section is intended for developers.
 +
 
 +
===Make Check===
 +
As shown above we can use <code>xmllint</code> to validate the syntax of account templates, if they include the namespace header. PR [{{URL:GH}}Gnucash/gnucash/pull/300 Adjustment of Account Hierarchy Templates. #300] now shows, we should at least determinate the direction.
 +
 +
* If we want this, we have to adjust the old files.
 +
** If a template got modularized, should all parts get the full header (like above) or
 +
** use DOCTYPE definition like <syntaxhighlight lang="xml">
 +
<!DOCTYPE gnc-account-example ... [ ... ]>
 +
</syntaxhighlight>
 +
***with PUBLIC <syntaxhighlight lang="xml">
 +
<!DOCTYPE gnc-account-example PUBLIC "FIXME"
 +
    "http://www.gnucash.org/XML/" [ ... ]>
 +
</syntaxhighlight>
 +
***or SYSTEM <syntaxhighlight lang="xml">
 +
<!DOCTYPE gnc-account-example SYSTEM "libgnucash/doc/xml/FIXME.dtd" [ ... ]>
 +
</syntaxhighlight>
 +
* Were there changes in the current parser required?
 +
* Would it be worth the huddle?

Latest revision as of 02:48, 22 April 2024

Creating localized Account Hierarchy Templates.

Directory of currently shipped templates

Motivation and Overview

Sometimes the standard GnuCash account hierarchy template needs a bigger rework before it fits the requirements of your government - especially for business purposes. In this case it might be better to start by creating a new hierarchy template from scratch.

Depending on your experience and resources there are different approaches:

and do some Copy&Paste #Adjust the Header #... and the Footer with your preferred text editor.
Conventions
Do not use the colon : in account names. It is by default used as account separator symbol.
Mark accounts, which contain subaccounts as placeholder.
Do not prefix the account name with the account number. There is a separate field for them.
Try to keep the account names short. You can put more details in the description and notes fields.
Important
In all cases you want to run the #Syntax Check before sharing your file.

Create an Example File

Usually you will start with an empty file or a similar - e.g. an older version - template, but it is also possible to strip down the copy of a working gnucash file.

Start with an new empty gnucash file

  1. After starting gnucash in the Chart of accounts (CoA) —usually in a tab named Accounts— enable useful columns, see the images currently only in the german Manual:
    List of useful columns and their xml tags
    Account Name
    required: <act:name>
    Type
    required: <act:type>
    Account Code
    alphanumerical Account Number, optional, allows a different order than alphabetical by name: <act:code>
    Description
    optional, if account name needs explanations: <act:description>
    Notes
    optional, e.g. instructions for the user: <slot:key>notes</slot:key>
    Tax info
    optional, currently only in DE and US of interest: <slot:key>tax-related</slot:key>
    Hidden
    optional, you shouldn't use it, but the user can hide currently unused accounts later
    Placeholder
    optional, write protection for group headers: <slot:key>placeholder</slot:key>
    They will also not appear in the dropdown list so select accounts.
    Opening Balance
    You need exactly one account with this flag in the whole resulting file. That is not easily to verify for a modular template. It will be the counter account when users add a opening balance using the assistant:
    <slot:key>equity-type</slot:key>
    <slot:value type="string">opening-balance</slot:value>
    
    Account Color
    optional, don't use it! It is a question of personal taste and capabilities.
  2. Create the account hierarchy, which is according your needs.
  3. Usually you should mark accounts which have subaccounts as Placeholder.
  4. Before you save to file in xml format, uncheck Edit->Preferences->General->Files:Compress Files to get an uncompressed xml file.

FIXME: I am not quite sure whether "Save file" or "Export hierarchy" is the better choice currently. One obvious difference: export saves no transactions, but also other parts will be ignored. (E.g. what will happen with taxtables, but it seems only accounts can be created.)

Strip data from an existing, uncompressed gnucash xml file

You have a nice working GnuCash file and somebody asks for a copy of your template. So you want to remove all your personal data. But you surely want to keep the accounts and in business templates the tax table.

Open the copy of the file with a text editor, preferably one that provides syntax highlighting for xml. Remove unwanted sections:

<book:slots> ... </book:slots>
<gnc:count-data ...>        <!-- give you an overview, and should be adjusted at the end -->
<gnc:commodity version="2.0.0">...</gnc:commodity>   <!-- remove only foreign currencies -->
<gnc:transaction version="2.0.0">...</gnc:transaction>
<gnc:budget version="2.0.0">...</gnc:budget>
<gnc:GncCustomer version="2.0.0">...</gnc:GncCustomer>
<gnc:GncEntry version="2.0.0">...</gnc:GncEntry>
<gnc:GncInvoice version="2.0.0">...</gnc:GncInvoice>
<gnc:GncVendor version="2.0.0">...</gnc:GncVendor>
<!-- feel free to add that which I missed like employee, price, order... -->

Now run a #Syntax Check.

Convert the Example into a Template

Extensible Stylesheet Language Transformations

XSLT is a powerful language for converting XML files into other formats. GnuCash has several XSL files in contrib/xslt. Unfortunately the contrib directory is currently not part of the installation. The XSLs can be processed by the program xsltproc, which is part of a package libxslt-tools or similar. Example for a compressed file:

gunzip -c <your gnucash file> | \
       xsltproc --stringparam title "Spacecraft project" \
                --stringparam short-description "Accounts useful for space exploration" \
                --stringparam long-description "A set of accounts useful for space exploration. Implements NASA Standards FOO-1234-BAR and FOO-3456-BAZ for Earth Orbit Satellites, Earth Orbit Space Stations, Solar System Manned and Unmanned Spaceflight, and Interstellar Exploration." \
                gnc2xea.xsl -
  • For uncompressed files start from line 2 and replace the last - by your filename.
  • gnc-act:exclude-from-select-all (see below) will be set.
  • Because there was a change after the xsl was written, you still need to change #... the Body ....

See gnc2xea.xsl in xslt README.

Manually

In case xsltproc fails, you want some adjustments or you want to understand the differences read this section.

Adjust the Header

After you have saved your template, you must manually adjust the first lines (the "header") of your newly created file as follows. Otherwise the "New File Wizard" will not know how to handle your template. The file name itself does not matter (it will not be visible anywhere), but the first lines of the file must contain the following information:

 1 <?xml version="1.0" encoding="utf-8" ?>
 2 <gnc-account-example 
 3   xmlns="http://www.gnucash.org/XML/"
 4   xmlns:act="http://www.gnucash.org/XML/act"
 5   xmlns:addr="http://www.gnucash.org/XML/addr"
 6   xmlns:bgt="http://www.gnucash.org/XML/bgt"
 7   xmlns:billterm="http://www.gnucash.org/XML/billterm"
 8   xmlns:book="http://www.gnucash.org/XML/book"
 9   xmlns:bt-days="http://www.gnucash.org/XML/bt-days"
10   xmlns:bt-prox="http://www.gnucash.org/XML/bt-prox"
11   xmlns:cd="http://www.gnucash.org/XML/cd"
12   xmlns:cmdty="http://www.gnucash.org/XML/cmdty"
13   xmlns:cust="http://www.gnucash.org/XML/cust"
14   xmlns:employee="http://www.gnucash.org/XML/employee"
15   xmlns:entry="http://www.gnucash.org/XML/entry"
16   xmlns:fs="http://www.gnucash.org/XML/fs"
17   xmlns:gnc="http://www.gnucash.org/XML/gnc"
18   xmlns:gnc-act="http://www.gnucash.org/XML/gnc-act"
19   xmlns:invoice="http://www.gnucash.org/XML/invoice"
20   xmlns:job="http://www.gnucash.org/XML/job"
21   xmlns:lot="http://www.gnucash.org/XML/lot"
22   xmlns:order="http://www.gnucash.org/XML/order"
23   xmlns:owner="http://www.gnucash.org/XML/owner"
24   xmlns:price="http://www.gnucash.org/XML/price"
25   xmlns:recurrence="http://www.gnucash.org/XML/recurrence"
26   xmlns:slot="http://www.gnucash.org/XML/slot"
27   xmlns:split="http://www.gnucash.org/XML/split"
28   xmlns:sx="http://www.gnucash.org/XML/sx"
29   xmlns:taxtable="http://www.gnucash.org/XML/taxtable"
30   xmlns:trn="http://www.gnucash.org/XML/trn"
31   xmlns:ts="http://www.gnucash.org/XML/ts"
32   xmlns:tte="http://www.gnucash.org/XML/tte"
33   xmlns:vendor="http://www.gnucash.org/XML/vendor">
34 <gnc-act:title>
35   IGAS-2099
36 </gnc-act:title>
37 <gnc-act:short-description>
38   Intergalactic Accounting Standard, Stardate 2099
39 </gnc-act:short-description>
40 <gnc-act:long-description>
41   This is the Base Module of the Intergalactic Accounting Standard as transmitted on stardate 2099-01-01. You might also need the module "starfleet" or "klingon". ~Cpt. Picard
42 </gnc-act:long-description>
43 <gnc-act:exclude-from-select-all>1</gnc-act:exclude-from-select-all>
44 <gnc:account version="2.0.0">
45   <act:name>Root Account</act:name>
46   <act:id type="new">e24772da4864456b196be5a6301c6756</act:id>
47   <act:type>ROOT</act:type>
48   <act:commodity-scu>0</act:commodity-scu>
49 </gnc:account>

Annotations:

  • Line 1: encoding
You must save your file in the appropriate character encoding and note the used character encoding here! For possible values, see Locale Settings.
  • Line 2ff: Namespace
The parser in GC 2.2.x makes no use of it, but future versions might change.
Some details can be found in [1] or in gnucash-v2.rnc. Defining the namespace has the benefit, you can check the syntax of your file later with xmllint.
  • gnc-act:title
Enter a short, unique Name, which is shown in the table in the "New File Wizard" so that the user can choose this template. This name is usually also part of the filename, but the file name itself does not matter and is never shown to the user. This name is restricted to ONE line.
  • gnc-act:short-description
A one-line description shown in the table in the "New File Wizard"
  • gnc-act:long-description
A somewhat longer description which is shown in a text box in the "New File Wizard" if the user selects this template. This should explain the content and the efficient usage of the template to the user.
A nice example for the descriptions is in accounts/de_DE/acctchrt_wohnungsw.gnucash-xea, which Google translates to:
<gnc-act:title>Housing Accounts Framework </gnc-act:title>
<gnc-act:short-description>Chart of Accounts for the Real Estate Industry (as of 2012) </gnc-act:short-description>
<gnc-act:long-description>Chart of accounts for the housing industry according to GdW / Hammonia Verlag (now Haufe), as of 2012
Usage notes: https://wiki.gnucash.org/wiki/De/Wohnungswirtschaft
Creator: Christoph Franzen, christoph@(censored).de
</gnc-act:long-description>
Note the link to the wiki with more details!
  • gnc-act:exclude-from-select-all
Indicates whether this template should be selected if the user clicks the button "Select All". The business-related templates are probably rather special and should not be mixed with a general home-user account structure, so you should probably enable this flag by writing a "1" in here.
  • Root Account
Only the base module should have exactly one.
Because it is only used internally, do not translate it!
The accounts in the optional modules linked over <act:parent type="new">...</act:parent>

If you decide to copy&paste this template, please replace the root guid by a self generated with

  • either:
uuidgen | sed -e 's/-//g'
(Dependencies: uuidgen is part of util-linux and sed has its own package)
  • or use an online uuid generator like this one (any other one will do as well). Be sure to untick "Hyphens" to generate gnucash compatible guids. If you forget to untick it, or you use a site that doesn't offer this option, simply remove the hyphens yourself.

.

... the Body ...

Note how the account hierarchy is defined by each account having a "globally unique identifier" (guid) as the value of its act:id element. E.g 5df07084fb48f599732df308a71d8246 in the case of the root account. Any child account refers back to its parent by having the parent's guid as the value of its act:parent element.

 1 <gnc:account version="2.0.0">
 2   <act:name>Root Account</act:name>
 3   <act:id type="guid">5df07084fb48f599732df308a71d8246</act:id>
 4   <act:type>ROOT</act:type>
 5 </gnc:account>
 6 <gnc:account version="2.0.0">
 7   <act:name>Child account</act:name>
 8   <act:id type="guid">03a869e21f475e8e7a0688e32035ee9a</act:id>
 9   <act:type>ASSET</act:type>
10   <act:commodity>
11     <cmdty:space>ISO4217</cmdty:space>
12     <cmdty:id>SEK</cmdty:id>
13   </act:commodity>
14   <act:commodity-scu>100</act:commodity-scu>
15   <act:parent type="guid">5df07084fb48f599732df308a71d8246</act:parent>
16 </gnc:account>

When GnuCash creates a new file (book) based on an account hierarchy template, these guids should be replaced by new ones, to ensure there are no collisions, for example if several templates are combined when creating the book. Therefore you should change the value of the type attribute for the act:id and act:parent elements like this, as an indication that new guids should be generated:

<act:id type="guid"> / <act:parent type="guid">
-->
<act:id type="new"> / <act:parent type="new">
respectively.

Make sure you leave the actual guids intact, as the parent-child relations would otherwise break.

From 2.6.2 commit [{{URL:GH}Gnucash/gnucash/commit/1e303f5d211fa41 Replace type="guid" with type="new" in gnucash-xea files]: Having type="guid" causes the accounts created from the file to use the example GUID instead of generating a new one.

And if you used the XSLT, replace all occurrences of

<slot xmlns="">
by
<slot>
.

From Comment 19 of Update of "wohnungsw" template.

This is an sample shell script doing the conversion and replacing the above mentioned parts after that:

#!/bin/sh
BAK=`date +%Y%j%H%M%S`
for D in $@
do
 KRXEA="$D.xea"
 if [ "$D" = "KRI" ]
 then
  KRXAC="$D.xac.gz"
  TITLE="Kontenrahmen für die Wohnungswirtschaft"
  SHORT="Kontenrahmen für die Immobilienwirtschaft (Stand 2012)"
  LONG="Kontenrahmen für die Wohnungswirtschaft nach GdW / Hammonia Verlag (jetzt Haufe), Stand 2012
Hinweise zur Verwendung: https://wiki.gnucash.org/wiki/De/Wohnungswirtschaft
Ersteller: Christoph Franzen, christoph@alte-pflasterei.de"
 elif [ "$D" = "SKR49" ]
 then
  KRXAC="$D.gnucash"
  TITLE="Kontenrahmen SKR49 für Vereine, Stiftungen, gGmbHs"
  SHORT="Datev-Kontenrahmen SKR49 für Vereine, Stiftungen und gemeinnützige GmbHs"
  LONG="Ein Kontenrahmen für Vereine nach dem SKR49 der Datev

Bei Gebrauch dieses Kontenrahmens sind die allgemeinen Konten abzuwählen.
An dem Rahmen sind selbstverständlich noch Anpassungen erforderlich,
bis man den seinen Bedürfnissen entsprechenden Kontenplan hat.
Hinweise zur Verwendung: https://wiki.gnucash.org/wiki/De/SKR49

Ersteller: Michael Braun 2009, michael-developer@fami-braun.de
Formalia für GnuCash-Vorlagen: Frank H. Ellenberger 2009
Erweitert auf den Stand 2018: Christoph Franzen 2017-2018, christoph@alte-pflasterei.de"
 else
  exit 
 fi
done
mv "$KRXEA.gz" "$KRXEA.$BAK.gz"
gunzip -c $KRXAC | xsltproc --stringparam title "$TITLE" --stringparam short-description "$SHORT" --stringparam long-description "$LONG" gnc2xea.xsl - | sed -e "s/act:id type=\"guid/act:id type=\"new/g" > "$KRXEA.tmp"
sed -e "s/slot xmlns=\"\"/slot/g" < "$KRXEA.tmp" > "$KRXEA"
gzip -N9 "$KRXEA"

... and the Footer

Close to the end of the file, you should replace

</gnc-v2>

by

</gnc-account-example>

.

Clean up

Depending on the way you created the template, there can be some redundant elements in your template. If you are unsure, you can ask the maintainers to do this part for you.

Unwanted Elements

Slots
Information about Online Banking is different for each person. Example FinTS/HBCI:
    <slot>
      <slot:key>hbci</slot:key>
      <slot:value type="frame"/>
    :
    </slot>
Account Colors are a question of personal taste:
    <slot>
      <slot:key>color</slot:key>
      <slot:value type="string">...</slot:value>
    </slot>

Elements with Default Values

Slots
Empty notes:
    <slot>
      <slot:key>notes</slot:key>
      <slot:value type="string"></slot:value>
    </slot>
Unset Placeholder flags:
    <slot>
      <slot:key>placeholder</slot:key>
      <slot:value type="string">false</slot:value>
    </slot>
Account Elements
Finally, if you removed slots, you can end with an empty slots element in some accounts:
  <act:slots>
  </act:slots>
If you find them, you can remove them.

Testing

From time to time you should check the syntax and finally by using your file in GnuCash.

Syntax Check

Finally you should run

for one file
xmllint --noout <mytemplate>
or multiple files
for i in *-xea; do echo $i; xmllint --noout $i; done

to verify the syntactical correctness (std well-formed check) of your file. No output means that no errors were found.

If xmllint is missing on your computer see Translation#Prerequisite.

Testing in Gnucash

  • If you have the sources and are able to build and install GnuCash from them then make your changes in the source directory and build and install GnuCash as usual.
  • If not, you want to modify GnuCash installed by a package manager, the Microsoft Windows GnuCash Installer, or a macOS application bundle, locate the installed templates directory:
    • Linux/BSD distribution package manager: /usr/share/gnucash/accounts. You'll need root privs to write to this directory.
    • macOS application bundle: Gnucash.app/Contents/Resources/share/gnucash/accounts
    • macOS package manager: share/gnucash/accounts in the package manager's installation directory, /opt/local is the default for MacPorts and /usr/local/Cellar is the default for Homebrew.
    • Microsoft Windows installer: C:\Program Files (x86)\gnucash\share\gnucash\accounts. You'll need to use a CMD or Powershell window running as administrator to write to this directory.
  1. gnucash --nofile
    
  2. File->New File
  3. go to Step 4—Choose accounts to create and select either for
    personal templates
    Select All or
    business templates
    Clear All and manually select your template
  4. Step 5—Setup selected accounts verify that
    1. each account with a triangle on the left is marked as placeholder on the right side and
    2. you can enter an Opening Balance for at least one leaf account of your Assets branch.
      If that fails, your template is missing exactly one account usually named Opening Balance in your Equity branch with a slot
          <slot>
            <slot:key>equity-type</slot:key>
            <slot:value type="string">opening-balance</slot:value>
          </slot>
      

A sample script for big templates

If the template is really big - as the german one - and you have it as a text file, it might be less work to adjust the following script from [2] to create the gnucash template. There are tools available on the internet and probably on your computer to convert often used formats such as PDF to plain text files e.g. pdftotext.

#! /bin/bash

# This application takes a text input file $FILE
# and converts it into a gnucash account scheme with a random name.
# The input file is read line by line where each line
# should be formatted as
#  number name (no leading spaces)
# or
#  category name (one leading space)
# .
# Empty lines are not allowed, number is expected to have 4 digits.
# The output is a two layer structure
# of all accounts. Whenever the first
# digit of number changes, a new source group is created.
# Whenever a new category line is passed, all following
# accounts are put below.
#
# Example:
# input:
#   1234 A
#   2000 B
#    Type B1
#   2001 B1a
#   2002 B1b
#    Type B2
#   2010 B2a
#   2011 B2b
# output:
#   Class 0
#   Class 1
#    \- 1234 A
#   Class 2
#    \- 2000 B
#    \- Type B1
#       \- 2001 B1a
#       \- 2002 B1b
#    \- Type B2
#       \- 2010 B2a
#       \- 2011 B2b
#
# (C) 2009, Michael Braun, michael-developer@fami-braun.de
# Distributed under GPL v3.0 or newer.
# see http://www.gnu.org/licenses/gpl.html for details

echo "start"

FILE="<source>.txt"

if [ ! -f "$FILE" ]; then 
 echo "no such file $FILE"
 exit 1;
fi

getuid()
{
 dd if=/dev/urandom bs=1 count=32  2>/dev/null | md5sum | awk -F' ' '{print $1}';
}

OUT="$(getuid).gnucash"

ROOT=$(getuid);
NUM=$(cat $FILE | wc -l)
NUM=$(expr $NUM + 1);
ID=0

echo -n > $OUT;

cat >> "$OUT" <<EOF
<?xml version="1.0" encoding="utf-8" ?>
<gnc-account-example
     xmlns:gnc="http://www.gnucash.org/XML/gnc"
     xmlns:gnc-act="http://www.gnucash.org/XML/gnc-act"
     xmlns:act="http://www.gnucash.org/XML/act"
     xmlns:book="http://www.gnucash.org/XML/book"
     xmlns:cd="http://www.gnucash.org/XML/cd"
     xmlns:cmdty="http://www.gnucash.org/XML/cmdty"
     xmlns:price="http://www.gnucash.org/XML/price"
     xmlns:slot="http://www.gnucash.org/XML/slot"
     xmlns:split="http://www.gnucash.org/XML/split"
     xmlns:sx="http://www.gnucash.org/XML/sx"
     xmlns:trn="http://www.gnucash.org/XML/trn"
     xmlns:ts="http://www.gnucash.org/XML/ts"
     xmlns:fs="http://www.gnucash.org/XML/fs"
     xmlns:bgt="http://www.gnucash.org/XML/bgt"
     xmlns:recurrence="http://www.gnucash.org/XML/recurrence"
     xmlns:lot="http://www.gnucash.org/XML/lot"
     xmlns:cust="http://www.gnucash.org/XML/cust"
     xmlns:job="http://www.gnucash.org/XML/job"
     xmlns:addr="http://www.gnucash.org/XML/addr"
     xmlns:owner="http://www.gnucash.org/XML/owner"
     xmlns:taxtable="http://www.gnucash.org/XML/taxtable"
     xmlns:tte="http://www.gnucash.org/XML/tte"
     xmlns:employee="http://www.gnucash.org/XML/employee"
     xmlns:order="http://www.gnucash.org/XML/order"
     xmlns:billterm="http://www.gnucash.org/XML/billterm"
     xmlns:bt-days="http://www.gnucash.org/XML/bt-days"
     xmlns:bt-prox="http://www.gnucash.org/XML/bt-prox"
     xmlns:invoice="http://www.gnucash.org/XML/invoice"
     xmlns:entry="http://www.gnucash.org/XML/entry"
     xmlns:vendor="http://www.gnucash.org/XML/vendor">
<gnc:count-data cd:type="account">$NUM</gnc:count-data>
<gnc:account version="2.0.0">
  <act:name>Root Account</act:name>
  <act:id type="new">$ROOT</act:id>
  <act:type>ROOT</act:type>
  <act:commodity-scu>0</act:commodity-scu>
</gnc:account>
EOF
LAST=0
CURR=$(getuid);
CURRSUB=$CURR;

addkontenklasse() {
echo
echo -n "add kontenklasse $LAST";
cat >>"$OUT" <<EOF
<gnc:account version="2.0.0">
  <act:name>Kontenklasse $LAST</act:name>
  <act:id type="new">$CURR</act:id>
  <act:type>ASSET</act:type>
  <act:commodity>
    <cmdty:space>ISO4217</cmdty:space>
    <cmdty:id>EUR</cmdty:id>
  </act:commodity>
  <act:commodity-scu>100</act:commodity-scu>
  <act:description>Erträge</act:description>
  <act:slots>
    <slot>
      <slot:key>placeholder</slot:key>
      <slot:value type="string">true</slot:value>
    </slot>
  </act:slots>
  <act:parent type="new">$ROOT</act:parent>
</gnc:account>
EOF
echo " done";
}

addkontenklasse;

addkontengruppe() {
echo
echo -n "add kontengruppe $1";
cat >>"$OUT" <<EOF
<gnc:account version="2.0.0">
  <act:name>$ID $1</act:name>
  <act:id type="new">$CURRSUB</act:id>
  <act:type>ASSET</act:type>
  <act:commodity>
    <cmdty:space>ISO4217</cmdty:space>
    <cmdty:id>EUR</cmdty:id>
  </act:commodity>
  <act:commodity-scu>100</act:commodity-scu>
  <act:description>$1</act:description>
  <act:slots>
    <slot>
      <slot:key>placeholder</slot:key>
      <slot:value type="string">true</slot:value>
    </slot>
  </act:slots>
  <act:parent type="new">$CURR</act:parent>
</gnc:account>
EOF
echo " done";
}

addkonto() {
cat >>"$OUT" <<EOF
<gnc:account version="2.0.0">
  <act:name>$1 $2</act:name>
  <act:id type="new">$(getuid)</act:id>
  <act:type>ASSET</act:type>
  <act:commodity>
    <cmdty:space>ISO4217</cmdty:space>
    <cmdty:id>EUR</cmdty:id>
  </act:commodity>
  <act:commodity-scu>100</act:commodity-scu>
  <act:description>$2</act:description>
  <act:code>$1</act:code>
  <act:parent type="new">$CURRSUB</act:parent>
</gnc:account>
EOF
}

while (true); do
 LL=$REPLY
 read
 if [ "x$REPLY" = "x" ]; then
   echo
   echo "end of file after $LL";
   break;
 fi
 REPLY=$(echo "$REPLY" | sed 's/\s\+/ /g');
 KTOID=$(echo "$REPLY" | sed 's/ .*//');
 NAME=$(echo "$REPLY" | sed 's/^[0-9]\+ \+//');
 if [ -z "$NAME" ]; then
   NAME="dummy";
 fi
 #echo "$REPLY => $KTOID | $NAME";
 echo -n "$KTOID "
 if [ -z "$KTOID" ]; then
   CURRSUB=$(getuid);
   ID=$(expr $ID + 1);
   addkontengruppe "$NAME";
 else 
  if [ $KTOID -gt "$LAST"999 ]; then
   # new cat
   LAST=$(echo $KTOID | sed 's/\(.\).*/\1/');
   CURR=$(getuid);
   CURRSUB=$CURR;
   ID=0
   addkontenklasse;
  fi
  addkonto "$KTOID" "$NAME"; 
 fi
done < "$FILE"

echo "</gnc-account-example>" >> "$OUT";
echo "done: written to $OUT"

Annotations

There are a few terms in the script, you might wish to adjust or at least understand:

  • Kontenklasse: account class, first level in the account hierarchy.
  • kontengruppe: account group, lower node in the tree, but not a leaf.
Both above are placeholders.
  • Konto: account.
  • Erträge: earnings.
  • <cmdty:id>: 3-letter ISO-currency symbol.
  • <act:commodity-scu>: smallest currency unit, in most cases 100 {C/S}en[t]*|P[f]en* or whatever.

Eventually you wish the account code $1 only in <act:code> and not in <act:name>.

Exporting an existing account hierarchy

You can create an account hierarchy template using this method.

  • You already have a account hierarchy in a gnucash file, but you want to export a subset
  • Go to file > export > export the xml
  • Select the subset you want from the xml as a starting point
  • Change the file xml structure according to the rules defined on this page
  • Take care when you change the xml file: ids and other information may conflict with your current account hierarchy
  • Put the xml file you edit in /usr/share/gnucash/your_language/yourfilename.gnucash-xea
  • Restart Gnucash
  • Use the New Account Hierarchy wizard to import your new account hierarchy

Back to Translation


Future Development

This section is intended for developers.

Make Check

As shown above we can use xmllint to validate the syntax of account templates, if they include the namespace header. PR Adjustment of Account Hierarchy Templates. #300 now shows, we should at least determinate the direction.

  • If we want this, we have to adjust the old files.
    • If a template got modularized, should all parts get the full header (like above) or
    • use DOCTYPE definition like
      <!DOCTYPE gnc-account-example ... [ ... ]>
      
      • with PUBLIC
        <!DOCTYPE gnc-account-example PUBLIC "FIXME"
            "http://www.gnucash.org/XML/" [ ... ]>
        
      • or SYSTEM
        <!DOCTYPE gnc-account-example SYSTEM "libgnucash/doc/xml/FIXME.dtd" [ ... ]>
        
  • Were there changes in the current parser required?
  • Would it be worth the huddle?