Just like with the previous alpha release, the first beta release of Gnucash for Android is now available.
In the last post announcing the second alpha release of GnucashMobile for Android, I promised to go into more detail about how to interact with Gnucash through Intents.
The alpha2 release introduced support for third-party applications to record transactions and create accounts using Intents on Android. These are the only two operations which are currently supported through intents. Deleting accounts and transactions is not supported, neither is retrieving a list of accounts and/or transactions.
You happen to be creating some awesome new Android app which allows users to pay for things or otherwise perform financial transactions like receive money (e.g. Paypal) etc. It so happens that your user is also using GnucashMobile to track her finances. What is the nice thing to do? Automatically record transactions for the user of course. This is one of the strong suits of the Android platform, cross-application communication.
First, you will need to declare permissions in your app which allow you to create accounts and transactions. This will enable the user to see upon installation that the application is indeed allowed to manipulate her Gnucash data.
It is recommended that each application should create an account for its own transactions. If you do not do so, your transactions will be recorded, but never seen by the user since there will be no account associated with them. Transactions are strongly bound to the accounts in which they occur. In order to create an account and a transaction, you need code that looks like the following:
Some notes about the account creation intent extras:
- EXTRA_TITLE is just that, the name of the account.
- EXTRA_UID allows you to specify a unique identifier for the account, maximum of 22 alphanumeric characters. This unique identifier is the same which will be used when creating transactions (see below) to assign them to this account. Try to make this something which will be unique to your app, because the database will reject any account with a duplicate UID.
- The extra “org.gnucash.extra.currency_code” is the ISO 4217 currency code which specifies what currency the account will use.
- Finally, the mime type is very important. This will allow Android to route your intent directly to the GnucashMobile app which should be the only one declared to handle that type. If it is absent, your request could go to any one of a dozen apps which handle Intent.ACTION_INSERT.
Now, notes about the transaction creation intent extras:
- The mime type for transactions should also always be included for the same reasons as for the account
- Intent.EXTRA_TITLE is the description of the transaction. Usually a short descriptive name.
- Intent.EXTRA_TEXT is for more text details about the transaction.
- “org.gnucash.android.extra.amount” allows you to specify the amount of the transaction as a double.
- “org.gnucash.android.extra.account_uid” allows you to specify the account to which this transaction belongs. Should typically be an account which you created for your app. So this should be the same value as Intent.EXTRA_UID for accounts
Lastly some general notes about transactions.
- You cannot specify a unique Identifier for a transaction, as that is automatically generated for each transaction.
- Also, the time of the transaction will be the time when the broadcast reaches Gnucash Mobile. So you should send your broadcast as close to the actual transaction time as possible. There is no facility for specifying this in the intents.
- Note that transactions also take the currency of their accounts. So you cannot store transactions in Euros in an account which uses US dollars.
So there you go, you can now record intents directly from your app and your users will love you for it. I look forward to an ecosystem building around this where users will simply be able to open Gnucash and see a history of all their transactions from different applications.
So I was accepted into the Google Summer of Code (GSOC) 2012 program under the GNOME Foundation. I will be working on extending Gnucash to the Android platform through the development of a mobile application for expense tracking. Thanks to the Gnucash folks and my mentor (Muslim Chochov) for guidance through the application phase . Much appreciation also goes to the GNOME foundation for enabling this opportunity.
The mobile application codenamed ‘Gnucash Mobile’ will enable users to be able to record financial expenses which are made on-the-go. A lot of expenditure happens in cash and can amount to much over time. Therefore, being able to track how and where expenses are made is important to building a complete picture of one’s finances. The expenses can later be exported to an Open Financial Exchange (OFX) file and can be imported into the Gnucash for the desktop.
The GSOC program is currently in the community bonding and preparatory phase for the actual coding which begins on the 21st May 2012. Accordingly, I have created a Google document outlying my design proposal for both the data model and the user experience of Gnucash Mobile. The application seeks to support the modern Android design guidelines, while maintaining compatibility with Android devices from API level 7 and above. The photo on the left is a mockup of how the main accounts page of Gnucash mobile should look like.
The application will make use of the ActionBar pattern in Android pervasively. Since the ActionBar is only available from Honeycomb upwards, backwards compatibility will be maintained through the use of the Android compatibility library and the ActionBarSherlock library. ActionBarSherlock enables the use of modern Android design paradigms on older Anrdroid API levels (7+).