Help with Xero Integration

If you have questions or if you want to share your opinion about Aware IM post your message on this forum
Post Reply
Gabbitas
Posts: 325
Joined: Sun Jan 03, 2010 3:36 am

Help with Xero Integration

Post by Gabbitas »

Hi Guys, I think I'm going to need some help......

I've never experimented with awareIM REST but the time has come to try and get my app to talk with Xero accounts. I know there are some real REST pros on this forum and I really hope you may be able to lend a hand. I've done a lot of reading on Xero documents and REST in AwareIM and its slowly starting to sink in and make some glimmer of sense to me but still so many unanswered questions in my mind!

My first question is this:

When I registered as a developer at developer.xero.com and I register my app and credentials it is asking for an "OAuth 2.0 Redirect URL" how do I know what this is? How do I generate this URL?

My second question is this:

Does anybody have a working example of a Xero integration that they would be willing to share? Long shot I know!!

Many thanks in advance

Andy
hpl123
Posts: 2203
Joined: Fri Feb 01, 2013 1:13 pm
Location: Scandinavia

Re: Help with Xero Integration

Post by hpl123 »

Codrin or support already has a plugin for Xero if I´m not mistaking, ask Vlad about it. For the REST pros, I would still be interested to hear replies to the question about URL as it´s not much info about REST etc. in the documentation and forum.
Henrik (V8 Developer Ed. - Windows)
aware_support
Posts: 7173
Joined: Sun Apr 24, 2005 12:36 am
Contact:

Re: Help with Xero Integration

Post by aware_support »

We do have a plugin for XERO, which was developed even before REST functionality became available in Aware IM. Therefore, we have never tried this integration using native Aware IM REST capabilities without using the plugin.
But it should be possible in theory.

As far as the redirect URL is concerned:

http(s)://YourServerName:YourServerPort/WebApplicationName/req.awurl

where WebApplicationName is by default AwareIM
Aware IM Support Team
tford
Posts: 4178
Joined: Sat Mar 10, 2007 6:44 pm

Re: Help with Xero Integration

Post by tford »

Andy,

I agree with Henrik .. please share your learnings along the way.

Sorry I can't help as I have not used REST functionality.
Last edited by tford on Mon Sep 28, 2020 9:09 pm, edited 1 time in total.
Tom - V8.5 build 2827 - MySql
Gabbitas
Posts: 325
Joined: Sun Jan 03, 2010 3:36 am

Re: Help with Xero Integration

Post by Gabbitas »

We do have a plugin for XERO, which was developed even before REST functionality became available in Aware IM. Therefore, we have never tried this integration using native Aware IM REST capabilities without using the plugin.
But it should be possible in theory.
Hi Support,

What does the plugin do? Does it work alongside the rest functionality or is it independant? If its independent I guess it would need to be re-written if Xero were to change something or introduce a new feature to their API? Does the plugin expose all current API capabilities and how much does it cost?

Thanks
aware_support
Posts: 7173
Joined: Sun Apr 24, 2005 12:36 am
Contact:

Re: Help with Xero Integration

Post by aware_support »

The plugin works independently from REST. It does not support all the API - it exports contacts, purchase orders and invoices into XERO, nothing else. The plugin is specific to a particular BSV, but can be changed to work with your BSV.

The price depends on what exactly you want to do with XERO in your BSV.
Aware IM Support Team
Gabbitas
Posts: 325
Joined: Sun Jan 03, 2010 3:36 am

Re: Help with Xero Integration

Post by Gabbitas »

I’ve managed to go from knowing nothing about REST a few weeks ago to now having a working demo BSV that’ll form the basis of the integration of Xero Accounting into my production application. Even after purchasing a couple of support tickets it’s been a bit of a mind blower for me with a lot of trial and error and I’ve found it hard to find any useful information on how others have accomplished REST integrations in their AwareIM applications. I’m posting my findings / learnings / notes as requested by others. I can’t promise it’ll make perfect sense, I can’t promise it’ll be entirely accurate and I can’t promise the terminology I’ll use will be correct but hopefully someone will find some use in it……

I’ll post the demo BSV as sometimes the best way to learn is by digging around something that works. Boy, I wish I had that a couple of weeks ago!
Enjoy!

These are the notes / steps I took when learning how to use XERO REST API in AwareIM:
1. Study the documentation for both the Xero API and AwareIM user guide. Then study them again and again! Xero docs here: https://developer.xero.com/documentatio ... /auth-flow

2. Some things to note here:
2.1 Your server must be set up to be using SSL
2.2 You server must not be running versions of TLS earlier than TLS 1.2
2.3 See this post here on issues with cookies in new version of chrome https://www.awareim.com/forum/viewtopic.php?f=1&t=11845

3. Create a user account at Xero Developers https://developer.xero.com/documentatio ... rted-guide

4. Create an oAuth2.0 app inside you xero developers account and fill out with your credentials
o AppName: YourAwareIMAppName
o Company or Application URL: https://www.YOUR_SERVER_NAME.co.uk
o OAuth 2.0 redirect URI: https://www.YOUR_SERVER_NAME.co.uk:443/AwareIM/req.awurl (Where AwareIM is the default app folder)

Once these details have been entered you can create your client_ID and client_secret (copy your client secret right away as it disappears soon
after creation)

5. Create an intelligent business object in your application (XeroRESTAPI) and select intelligence type REST. Enter all of the credentials as per the
demo BSV.

6. Some things to note here:
6.1 Scopes are general categories and broadly determine what you’ll be able to access when you start making calls to the API. Look at the
docs to see which best fit your needs.
6.2 API key and API secret (client_id and Client_secret) can be entered into system settings in the operation mode or hard coded in the REST
oAuth dialogue in the config tool. I don’t know if its possible to use the same key and secret in multiple BSVs so long as they are all hosted
on the same server? My suspicion is that this would be allowed.
6.3 The access token return type should be set to JSON else the token extractor will not extract the token and an error will be thrown.

7. Basic understanding of the oAuth code flow:
7.1 So long as there is no access_token stored in the database I.e in SystemSettings.AccessToken, AwareIM will begin the oAuth code flow
when a service of XeroRESTAPI is requested. Therefore to start the oAuth code flow you must have a correctly configured service defined.
In the case of xero this must be a service that doesn’t require ‘tenant_id’ http header (see further below about tenant_id). The service
configured in the demo app that doesn’t require this header is called ‘Connections_GET’. Funny enough….this is the service used to get
the ‘tenant_id’ from Xero!
7.2 AwareIM will contact the ‘Authorisation URL’ defined in REST settings and will automatically include the client_ID and client_secret (and scopes if defined)
7.3 When this call is made the browser will open a login page from Xero where the user can log in.
7.4 Once logged in, Xero will then present the user with a list of available organisations (further down known as tenants). The user selects one or more organisations for which your app may connect to and is then returned to your application.
7.5 At this point AwareIM collects the access_token and stores it in system settings (or wherever you choose to store it)

8. All of the above is automatically handled by AwareIM based on the settings defined in the REST enabled intelligent object. I believe that in some API’s that would be enough authorisation to get you going with making REST calls. In Xero there is another step:
8.1 Define a service that calls Xero and returns a list of authorised connections (also confusingly known as organisations or tenants). (SEE XERO DOCS GET https://api.xero.com/connections) (This service is named ‘Connections_GET’ in the demo app).
8.2 Store those returned connections / tenants in the AwareIM database.
8.3 From the list of returned connections / tenants, you must choose which tenant you wish to interact with. In the demo BSV this selection is made from within system settings. When a user chooses the tenant, rules populate SystemSettings.XeroTenantID with that of the chosen tenant.
8.4 From this point on, when making any call to Xero, one must include this SystemSettings.TenantID as a header using ‘Request HTTP Headers’ in the REST service settings dialogue in the AIM config tool. The header is defined as follows: Name: Xero-tenant-id Value: <<SystemSettings.XeroTenantID>>

9. Token expiry and refresh_tokens.
9.1 After AwareIM has collected the access_token in step 7.5 you will have 30 minutes to work with it before it expires. If you define token expiry parameters in the REST oAuth settings dialogue then AwareIM will automatically restart the request as in steps 7.2 to 7.5. above. The problem with this is that steps 7.2 to 7.5 require interaction with the user. In my opinion and my use case interaction with the user every 30 mins = not ideal!!
9.2 To over come this problem refresh_tokens must be used……….cue an email to support and 500 bucks later refresh_tokens are now supported (yes, I know, all these gifts for you!). There is now another couple of parameters to enter in REST settings similar to access_tokens. Now AwareIM automatically collects a new token every 30 minutes (so long as a service of xero is called. And what I mean here is that AwareIM will not just keep refreshing the connection if there is no reason to) Therefore the connection stays up indefinitely (or at least 30 days as that’s when a ‘refresh_token’ will expire if it hasn’t been used) so no interaction is required by the user to reverify themselves with Xero. Very slick. Thanks Vlad. As Xero returns its tokens in JSON format you’ll need to use this token extractor: "refresh_token"\s*:\s*"(\S*?)"

10. Using OpenAPI Definition.
10.1 Its possible to use an OpenAPI definition to help you ‘Discover Services’ of a REST API. The definition for Xero can be fond here: https://api.apis.guru/v2/specs/xero.com ... agger.json
10.2 Simply paste this URL in the REST Intelligent Object settings dialogue ‘Discover…’
10.3 Some points to note:
10.3.1 This will create ‘Services’ and ‘business objects’ representing service ‘parameters and replies’
10.3.2 This process doesn’t always seem to create all attributes for the reply and param objects nor does it create reference attributes.
10.3.3 For some reason when you make changes to “discovered” services and their auto created business objects they end up being reset back to the same state they were when they were first “discovered”. The reset happens when the REST intelligent business object is saved. This makes it a bit limited to say the least. Think this might be a bug or perhaps an issue with the definition? Who knows but I’ve made the decision to just define my own services and my own objects. I’ll let someone else decrypt this one.


11. Other things to trip you up:
11.1 If you get an error that says something along the lines of ‘No Protocol’ chances are that you have missed the ‘https://’ from your intelligent object> service settings> base URL. Simple but had me banging my head for an hour!
11.2 In rest settings there are fields so that one may define an object
11.3 Think about your naming convention for services early on as its difficult to change the name of a service later on. This is because AwareIM does not rename the service everywhere in the app (such as in rules and processes) in the same way it would do if you were to rename say, a, business object or a query or form etc.


How to use the Demo BSV

1. Go and create a Xero Developer account as per steps 3 and 4 above.
2. Log in the operation mode
3. Turn on Xero Integration
4. Enter Client ID and Client Secret copied from your xero developer account and save system settings object
5. Click on ‘Connect to Xero’ and enter log in details etc when prompted
6. Choose which xero tenant/organisation you wish to interact with
7. You should now be connected. Test the connection by clicking on ‘Test Connection’. If all is well, a message will display with organisation details.
8. Before moving on to the next step and if you’re using the Xero ‘Demo Company’ to connect: Go to Xero and log in to the Demo Company. Click on ‘Accounting’ > ‘Advanced’ > ‘Tracking Categories’ and delete the tracking category named “Regions”. Now go back to sample app in the operation mode.
9. Turn on ‘Sync Tracking Categories’ and then ‘Create New Tracking Categories on Xero’. This process will create two tracking categories on Xero. One called ‘Build Phase’ and another called ‘Cost Centre’.
10. A bit further down the page you’ll notice a query that will display build phase. Create / update / delete a few build phase and you’ll notice they’ll sync with Xero.
11. That’s all. Have fun.

How about this for an Idea:
Please feel free to use the demo BSV in any way you choose. Include it in your app or sell it to someone or do whatever you like. But might I ask that if you consider doing the following for the benefit of the AwareIM community:

If your intention is to have your application integrate with, say, Xero invoices then why not take this demo app, do your configuration work inside the demo, get it working and post it back to this thread for others to then do the same with their own integrations. It’s easy enough to copy paste the functionality out of a demo app and into your production app. In time this could provide a very comprehensive sample application for everyone to share. Perhaps we, as a community, should do the same with other apps too……just a thought.

BSV Here https://1drv.ms/u/s!AtaZUyxQx2otioUTk8_-MPeKehqHlw
hpl123
Posts: 2203
Joined: Fri Feb 01, 2013 1:13 pm
Location: Scandinavia

Re: Help with Xero Integration

Post by hpl123 »

Awesome man, thanks for sharing.
Henrik (V8 Developer Ed. - Windows)
tford
Posts: 4178
Joined: Sat Mar 10, 2007 6:44 pm

Re: Help with Xero Integration

Post by tford »

Thanks for investing the time to post such detailed notes & example BSV!
Tom - V8.5 build 2827 - MySql
Jaymer
Posts: 1758
Joined: Tue Jan 13, 2015 10:58 am
Location: Tampa, FL
Contact:

Re: Help with Xero Integration

Post by Jaymer »

+1 nice
Click Here to see a collection of my tips & hacks on this forum? Or search for "JaymerTip" in the search bar at the top.

Jaymer
Aware Programming & Consulting - Tampa FL
eagles9999
Posts: 2173
Joined: Mon Jul 02, 2012 12:24 am
Location: Ulaanbaatar, Mongolia

Re: Help with Xero Integration

Post by eagles9999 »

Excellent. Thanx for sharing.
Cheers,
Mark
_________________
AwareIM 6.0, 8.4, 8.5b (build 2806) MS SQL Server 2012 / MariaDB, Windows 10, Ubuntu Linux, Theme: Default, Browser: Chrome
Upcloud, AWS
Image
Post Reply