An example application demonstrating the use of the Perl WebService::Xero module to implement a Xero 'Public API Application'. This example of a Xero Public API Application provides a browser based application that Xero users can allow access to their accounts records. When the user authorises Xero access to the application, the application will show buttons that demonstrate access to Company Details, Contacts and Invoices.
You can see a working instance of this live here.
This example is aimed at those providing solutions to Accounting Service Providers but is suitable as a starter for any application that requires integration with multiple external Xero accounts.
- A Xero account configured with 'Public Application' API credentials as described in the 'My Apps' Tab in the Xero Developer Portal
- A development environment with Perl (Linux,Windows or Mac) including an installation of the CPAN WebService::Xero module (Version 1.2+) and the MojoLicious Real Time Web Framework
git clone https://github.com/pscott-au/mojolicious-xero-public-app-demo
cp test_config.tpl test_config.ini
## edit test_config.ini to include the Xero Public App API credentials
morbo ./myapp.pl
NB: Multi-process options such as hypnotoad not currently supported.
Open browser to http://localhost:3000/app/main to see the app wrapped in a debug container. OR Open browser to http://localhost:3000/app/ to just see the app running without diagnostics etc.
WARNING!!!!!
WARNING!!!!!
If you configure you ini file and API KEY with localhost as the domain you cannot use 127.0.0.1 and must use localhost !!!!!
I have more than once wasted an hour or so trying to debug this !!
WARNING!!!!!
WARNING!!!!!
When you click on the 'Authorise Xero' button you should then be redirected to Xero to confirm access and redirected to an authenticated application interface.
A quick way to create an rc.d script to run the mojo app as a system service is to use a gist as follows:
curl https://raw.githubusercontent.com/x13machine/ubuntu-demon-creator/master/create-demon.sh | sudo name="mojo-xero" username="peter" command="morbo /usr/local/src/mojolicious-xero-public-app-demo/myapp.pl" bash
I am currently expanding this in sync with the latest development version 1.2 of WebService::Xero. The development version is being refactored to include classes that describe Xero components and encapsulate the data in more detail than a simple struct or json object.
WARNING: If you don't use the above development version but use the production CPAN version then some of the functionality in this app will not work. I am anticipating an update to the release version before the end of May 2017.
In order to run in a production environment with hypnotoad, an approach to interprocess communication is required because the current approach of using a global variable to contain all the socket connections will not be shared across multi-processes. See Issue#1 for more details.
- Currently once you have a valid session the Company details are retrieved and used to construct the welcome screen with the name of the user's company and a few buttons to access Xero API endpoints. These buttons don't do anything at the moment.
- I am in the process of adding this functionality to retreive and provide nicely formatted data.
- Need to find a way to properly communicate how all of the components of this system interact - am considering use of https://p5js.org/ to create an animated model.
- I would also like to add in a local caching facility to minimise API calls and include default paging etc to pull all results where appropriate - will probably include in the WebService::Xero module.
This application includes a socket service that is used to provide diagnostic feedback to the main.html wrapper interface. This allows you to see the step-by-step protocol dialog as the Perl module negotiates the authenticated session with Xero. This socket layer is not required for you own applications and in the future I will provide some minimal starter applications that don't have this cruft.
The use of websockets introduces some new issues that I will discuss in the future with regard to SSL etc. Ideally we will provide a fully worked example with a container microservice and various configuration options to proxy through requests to this etc.