RSS Feed

Using Intents in Gnucash for Android

Posted on Monday, August 13, 2012 in Coding, User

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.

Share and Enjoy:
  • Twitter
  • Google Bookmarks
  • Digg
  • del.icio.us
  • Facebook

Bring on the comments

  1. Matt Mossholder says:

    This seems really nice. One question though, regarding the naming of the intents. I’m just starting out with writing Android apps, so I could be wrong, but isn’t it a best practice to make the intent app agnostic, so that multiple applications can provide the same service? That would make me think that having things like ‘org.gnucash.*’ and ‘vnd.org.gnucash.*’ wouldn’t be the proper way to go…

    Thanks for your efforts, I’m really looking forward to using this!

    • Ngewi Fet says:

      What you say is nice in theory, but the problem is there is no standard for financial transaction Intents.
      I prefer to use the default intent actions (Intent.ACTION_VIEW) and then differ in the extra details instead of defining my own like “org.gnucash.android.intent.action.VIEW” .

      I agree that it would be better if there were something widely adopted, since it will ease third-party implementations (not having to code for each app).
      Maybe we could define a standard starting with the Gnucash app. (but you know how standards processes work 😉

      Thanks for bringing it up though. We need more discussion around this.

  2. […] the original here: Using Intents in Gnucash for Android This entry was posted in Blog Search and tagged app, awesome, creating, happen, money, perform, […]

  3. […] option for accounting use on Android. Ongoing dialogue about GnuCash for Android development here: Using Intents in Gnucash for Android About GnuCash, the primary development site: Free Accounting Software | […]

  4. Vignesh Guttikar says:

    This is an excellent write-up and probably the only one on the net about the GNUCash integration using intent. I am able to get an account created and a UID generated, however transactions are not registering via intent. I have used the same code provided in this page as well as updated code based on dynamic data. As I am executing on my mobile device, I am not able to get the exceptions. Is there a way to get the exceptions or troubleshoot steps I can follow?

    Thanks for the article again.

Leave a Reply to Vignesh Guttikar

Click here to cancel reply.