Xero Integration

Overview

BigChange’s JobWatch system allows complete integration with your Xero financial software package. Once you have configured the initial setup in BigChange Administration, you can relax in the knowledge that information added within JobWatch will be seamlessly replicated within Xero without the need for double entry and eradicating concerns over missing or duplicated information.

Before Set Up

Before Set Up

When setting this up for the first time, please ensure that the following items have been set-up in advance:

  1. A valid add-on licence – this is allocated by BigChange and is required when first setting up the integration between JobWatch and Xero.
  2. Bank accounts – These are the bank accounts that are required to post transactions against.
  3. Account Codes  – These codes represent your sales and purchases and must be added to JobWatch prior to running the integration settings.  All codes must match the representative codes in Xero.  A downloadable list of Xero codes can be found here.
  4. Stock Codes – These codes represent the link between products in Xero and stock codes in JobWatch and must be added where you intend to include stock items to Invoices, Credit notes or Purchase orders. The ‘stock code’ field is used to link a stock record in JobWatch to an ‘item code’ in Xero.
  5. A Web User – this must be someone with administrative rights
  6. An email address – this will be used to receive notifications.
  7. Contact groups – Contact records in JobWatch are organised into groups based on their type, eg Account, Site, Prospect but Xero only has 2 default Contact Groups: Customers and Suppliers. To synchronise JobWatch contacts with Xero, you need to create Contact Groups specifically for this purpose, containing only information which you wish to sync, so that the 2 software correspond eg ‘Xero Contact’ or ‘Account Customer’
  8. Assign JobWatch Contacts – you now need to assign all of your JobWatch contacts to one or more of the groups that you created in (6).
  9. Account references –  these create the bond between the contact in JobWatch and the contact in Xero.  The account reference is unique to both contact records and is used when updating them or when creating a transaction against the contact record. Where an invoice is created against a contact record that is not in Xero, eg a site contact, the site contact must be linked to a parent record that is in both systems and has a valid account reference.The account reference is in the CRM Record in Financials → Terms.  When creating a contact record, an account reference and type must be specified.  The account reference must match the Xero contact record and the type must be set to 1 for Xero.
  10. A valid Xero company – ie you must have the Xero software, with username and password.

[download1]

Set Up & Syncing Video

Set Up

Set Up

This is how the data flow between BigChange and  Xero works:

To begin, navigate to: My account → Administration → [Quick Links] General Account Settings → Financial and ensure that the field ‘Financial Integration type‘ is set to Xero

Whilst still in the Administration screen, click on the Financials side menu and select Xero integration:

This will open a new popup which you should click on in order to connect:

Complete your log in details in the form below

Once you have logged in, JobWatch will request access to your company.  Click ‘Allow access’

A new screen will now open within JobWatch, which will determine the form of integration between the 2 software, so please take special care when completing it.

You will note the Xero disconnect button underneath the menu title.  This will send a delete request directly to the endpoint.

  1. Enter the licence in the textbox provided and click verify.
  2. The email address is used to record the person or persons you wish to receive emails. For multiple email addresses, separate by a comma.
  3. A linked user with full administration rights is required by the system for access to the JobWatch features when saving contacts, creating invoices etc.
  4. Xero provides up to two tracking categories which are analysis codes used on the transaction line. To utilise the tracking categories, simply import the tracking category codes into JobWatch.  Note these can be added after initial setup if required.  The tracking category names appear as column headings on your financial documents and appear on each transaction.
  5. Use the available checkbox to choose which feature(s) you would like to synchronise.
  6. Decide whether you wish Contact records to be synchronised from JobWatch to Xero or from Xero to JobWatch and the contact group(s) for the contact records that you wish to synchronise.
  7. The generate account reference option enables users to create a contact in JobWatch and automatically generate an account reference of the desired format. The contact reference format takes a sequence of letters from the contact name and appends a numerical sequence to it eg DAR0001 for Darlington International.  If this option is not selected, the user will be responsible for generating a unique reference no. manually and for setting the account type to 1 for Xero.
  8. When working with Xero tax codes, you must import the tax codes using the option provided and choose the tax codes that are appropriate to the tax type – Sales or Purchases.
  9. As there is no currency defined against the contact record, the default currency option is used when creating a contact record. When creating invoices, credit notes or purchase orders, the currency is defined against the transaction.  It is important to note that if using multiple currencies, the currency must also be set up in Xero.
  10. To match Xero, a user can define the status of invoices/credit notes and purchase orders by choosing the option that suits them. It is important to note that when choosing ‘draft’ or ‘submitted’ for Invoices, payment can only be recorded against an invoice once it has been authorised.
  11. This is a numerical field, used to add a number of days to the purchase order date. Select the number of days you wish to add.
  12. The default nominal (account codes) are used when processing invoices, credit notes and purchase orders. These codes work in conjunction with the tax code and are used when no nominal code is specified against a transaction.   In the same way that any nominal code is setup in JobWatch, the default nominal code must also exist in Xero.  Simply select from the dropdown menu. Note that these can also be imported by clicking on the ‘Import Xero Nominal Codes‘ button.
  13. The field updates the contact reference with the account reference. Note, the contact reference field is only used to provides a visual and search function, it has no impact on the synchronisation if changed. Simply select from the dropdown menu.
  14. The software will use the default bank account for processing payments against invoices when a bank account has not been specified against the transaction. This is important to consider when processing foreign currency transactions and payments from JobWatch.

Contact Synchronisation - JobWatch to Xero

Contact Synchronisation – JobWatch to Xero

Contract synchronisation will differ depending upon whether you chose to sync based upon entries made in JobWatch or in Xero during setup.

When synchronising from JobWatch to Xero, please ensure that: 

  • All account contacts have been organised into the correct group.  
  • All contacts records are linked to an existing contact record in Xero. 
  • All contacts have a valid, unique account reference that matches the corresponding Xero contact.
Contact Groups

Within JobWatch, Contact Groups can be found by navigating:  My Account → Administration → Contacts & notes → Contact groups.

  • Contact records are defined by these groups. For example all prospective customers might come under a group called ‘prospects’:

  • Some contacts that are referred to as customers are actually (child) site contacts which are linked to a parent contact record. Whilst jobs and invoices can be raised against these types of contactsthe invoice itself will go to the parent contact. Any site contact record that is linked to a parent should be organised into a separate contact group, ensuring that no site contacts are created in Xero.
  • Account Customers are parent contacts and any customers that have an account in Xero.  The integration software requires that all contacts that have a corresponding record in Xero are contained within a group.  This helps the program identify whether any contact in this group(s) should be synchronised with Xero.
  • Please note: Although it is possible to create more than one account or site group, a group cannot contain a mixture of parent and child contacts.
Creating a Contact Record

To create a new record, click on CRM and ‘New Contact’.  Now enter the name of the business or business address:

The software will first check whether or not the reference field is populated.  If the field has been left blank and the ‘Generate account ref’ box was ticked in setup

then a reference number will be generated.  The system will now connect to Xero and check whether a record for this contact already exists.  If not, it will create a record for this contact assuming that this was authorised in setup.

Please note, the Contact Reference outlined in the first image below, is used purely for record searching and is different from the Account Reference (image 2), generated when the record is synchronised with Xero.

Navigate: CRM → [side menu] Contacts → select contact → [tab] General:

Contact Reference

Navigate: CRM → [side menu] Contacts → select contact → [tab] Financials → [subtab] Terms:

Account Reference

Where you have:

a) Ticked ‘Generate account ref’ in setup
b) Left the Contact Reference field blank

JobWatch will auto-create an alpha-numeric code and the 2 Reference fields (Contact Reference and Account Reference) will match.  This will not be the case in either of the following scenarios:

a) You have manually populated the Contact Reference field within JobWatch
b) You did not tick the ‘Generate account ref’ in setup

Note it has also populated the ‘Account Type’ with 1, denoting Xero, as we selected ‘Xero’ from the dropdown menu in the Group field when completing the form for this Contact (see illustration for Contact Reference above).

This is how the Contact above appears in Xero:

Contact Synchronisation - Xero to JobWatch

Contact Synchronisation – Xero to JobWatch

When synchronising from Xero to JobWatch please ensure that: 

  • The contact record is assigned an account number  
  • The contact record is assigned a postal address  
  • The settings have been modified to include a default group
Contact Groups
  • There is no equivalent to JobWatch groups within Xero contact records.  When a record is created in Xero, the contact record applies the default group that is defined in the user settings.
      
  • Where a contact record already exists, the contact group is not considered, instead, the software reads the account number from Xero and updates the associated contact record within JobWatch.
Creating a Contact Record

To create a new record in Xero:

  1. Log in and navigate to: Contacts → All Contacts
  2. Select ‘Add contact’ and populate the fields, ensuring that there are unique entries for (a) contact name and (b) the account reference.  You must also ensure that the postal address field is completed.
  3. Populate the primary person, phone and ensure that you enter a single, valid email address in the relevant field
  4. Where a field is invalid or not unique, an error message will be displayed to prevent you from saving the information:
  5. Once a record is saved, the corresponding record will be created/updated within JobWatch
     
  6. Depending on the option selected during setup, the account reference will update the contact reference.

Synchronising Invoices, Credit Notes and Purchase Orders Video

Synchronising Invoices, Credit Notes and Purchase Orders Video

Synchronising Invoices, Credit Notes and Purchase Orders

Synchronising Invoices, Credit Notes and Purchase Orders

Introduction

Depending upon the options you selected in the JobWatch setup configuration, you can choose to synchronise certain types of financial documents from JobWatch to Xero.

When they have been selected in setup, Invoices, Credit Notes and Purchase Orders can all be added in the usual way within JobWatch, with options to mark as: ‘draft’, ‘submitted’ or ‘approved’.  Only ‘approved’ items can be synced.

To set the synchronisation in motion, mark the transaction as sent and it will automatically sync with Xero. Please be aware that once the document has been marked as sent, no further changes can be made to it.

Refresh your screen and you will see that a blue tick appears in the ‘Synced’ column as confirmation:

Any amendments made to the transaction in Xero once the document has been synchronised, will not be reflected in the JobWatch system.

Creating a New Invoice, Credit Note or Purchase Order

Creating a New Invoice, Credit Note or Purchase Order

Using an invoice as an example document, begin by navigating: CRM →  [side menu] Financial → [icon] New financial document

Populate the form, including a valid stock, account code, tracking categories and tax codes.  When all of the relevant information has been added, click to Save. JobWatch will have automatically allocated a Reference number where this was selected in Administration.

Once the document has been approved, mark it as sent and refresh your page.  After a short period, a blue tick will appear in the ‘Synced’ column to confirm that it has now synchronised within Xero.

You will also notice that the original invoice number assigned within JobWatch will be over-written with a new invoice number assigned by Xero.  Where you have automatic document sending in place, you may wish to add in a 60-minute delay to ensure that reference numbering is consistently applied.

Although the invoice reference number will be overwritten, the order number, whether from Job Group or Job, will appear in the Reference field within Xero to allow additional traceability:

Within JobWatch:

Within Xero:

If any of the required fields are missing information from the document, you will receive a default error message when the screen refreshes:


Go to the Notes tab and view the contact error for the invoice:

Click on the relevant note and press to Edit.  You will now be able to see precisely what remedial action you need to take in order to successfully process the entry:

Amend the document in the required manner, ie in the above example, we would need to add an invoice description line and then synchronise the invoice. Once the error has been corrected and the invoice or other financial document has been successfully synced, complete the Note to show that the issue has been resolved.

Adding Stock to a Transaction

Adding Stock to a Transaction

Whilst stock is not directly integrated with JobWatch, where stock items are added to a sales invoice, they must be linked to a corresponding stock item in Xero. To link stock items, you must create a link for the two items by modifying the stock record inJobWatchand add the corresponding product code from Xero to the stock code field. See below screenshot.  The field stock code must contain the product item code from Xero.

When you process an invoice, you must first ensure that there is stock available in JobWatch. Where an item is tracked, you must ensure that stock is available in Xero as well. The routine for adding stock to JobWatch has not changed. You must choose an item, and either serial number and location depending on whether the item is serial or consumable.

When synchronising the invoice, the routine will check the item in Xero to see if it is a tracked item. Where it is a tracked item, the routine will confirm whether enough stock is available to sell. Where this is not the case, the invoice will default to draft, otherwise, it will depend on the setting chosen in the user interface. It is the user’s responsibility to ensure that the stock in both systems is up to date.

Where a stock item is added to a credit note, the same rules apply but the routine will automatically increment the quantity of stock where the item is a tracked item in Xero.

Adding stock items to a purchase order

The process for posting a purchase order is the same as the invoice and credit note. The main difference is that a user will enter a supplier for the purchase order which must exist in Xero.

In the same way, you can add stock items to an invoice, a user can add stock items to a purchase order. The routine is the same, except that you do not need to specify the location or serial number. The routine will create the purchase order in Xero with the stock item added. The processing of the purchase orders is handled in Xero from that point forward irrespective of whether the item is tracked or not.

It is worth noting that the routine only creates a purchase order in JobWatch and Xero for the stock item(s). Any processing of invoices or stock receipts must be processed manually from this point forwards.

Payments

Payments

Payments can only be synchronised from JobWatch to Xero and will be drawn from either the default bank account added in the setup screen or one specified on the invoice.

To record a payment, navigate: CRM → [side menu] Financial documents → select document → [icon] Mark paid:

or from the invoice itself.  Navigate: CRM → [side menu] Financial documents → select document → Edit → (1) Payments → (2) Add → (3) Complete popup form

Where payment is to be made in a foreign currency, the Xero invoice which is generated from the payment will show the currency exchange rate against which it was made, as well as the usual payment details.

Payments cannot be made against invoices which have not already been synchronised with Xero, since they don’t exist on the Xero system.  Attempting to pay them will, therefore, result in an error note.  This is also true:

  • when an invoice has not been marked as ‘authorised’.
  • when a payment exceeds the value of the invoice.
  • if a payment currency does not match either:
    • the invoice currency or
    • the standard currency of your company

A fully synchronised invoice will display in this way within JobWatch:

and this way within Xero:

Whilst a payment cannot exceed an invoice value, it can be paid for values below the total, meaning that making one or more part payments is possible up to a total value of the invoice.  Part payments can be viewed in the Payments tab of the invoice:

Frequently Asked Questions

Frequently Asked Questions 

Q: How do I disconnect from Xero?

A: There is a Xero option to disconnect in the user interface settings in JobWatch

Q: How do payment processing fees appear in Xero?

A: Payments are made against invoices in JobWatch which are reflected in Xero. A payment is made against the Xero invoice and recorded in Xero as a receipt against the bank.  If no bank account is specified against the invoice in JobWatch, the process will use the default bank account specified in the Xero user interface in JobWatch.

Q: How do I reconcile sales data synced to Xero?

A: There are reports in Xero that analyse the invoices between two ranges based on status, currency etc.  You would run this report and cross-reference the postings made to confirm the data between the two systems.

Q: When and how does data sync occur? Is it manual, automatic, on login, in real-time? Are there any settings related to synchronizing?

A: When changes are made to a contact, invoice, purchase order, payment for example, a message is created and queued in our system ready to be processed.  The synchronisation occurs when the message is cleared.  This process depends on how much traffic but normally takes anywhere up to 10 seconds to process.

Q: Can I synchronise multiple contact records? 

A: The program responds to the saving of a contact record which is created/updated and exists in one of the groups defined in the settings.  It is possible to use the import function which will create records in Xero for each contact record that is imported. However, it is important to note that there is a daily 5000 API limit on the number of calls that can be made and we would recommend speaking to your implementor before using this method.

Q: What information is carried across when creating a contact in JobWatch? 

A: The contact name, contact street, city, country and postcode is read from JobWatch and populates the corresponding Xero postal address fields.

Q: I have created a person in JobWatch, but it wasn’t carried across.  Why?

A: The software has no concept of whether the person in JobWatch is a financial person or not.  In most instances, the Primary Person within JobWatch will not be the person responsible for finances.

Q: Why do I need to organise my contacts into groups?

A: Contact records must be organised into groups to ensure that the interface only creates/updates contact records that are account contacts.  You can create multiple groups but all contacts within each group must be of the same type only ie you can’t mix parent and site (child) contacts.

Q: There are fields for credit limit and payment terms in JobWatch, can these be populated? 

A: There are currently no fields available for credit limit or payment terms in Xero. This may be something that can be added in future if the features are available.

Q: Why can’t I create contacts in both systems? 

A: The integration interface responds to changes made in JobWatch and Xero when a record is saved.  If a record is saved in JobWatch, it would respond by then saving the same record in Xero and so attempting to use both would result in multiple entries for the same contact in a perpetual circle of changes.  Whilst certain safeguards have been added to JobWatch, there are no equivalent mechanisms in the Xero API.

Q: Why is synchronisation from Xero to JobWatch not instantaneous?

A: The interface looks for changes that are made to Xero but the frequency of triggering these events is controlled by Xero and only takes place periodically.

Q: When I create the invoice in JobWatch and synchronised it to Xero,  can I view the PDF copy of the invoice in Xero?

A: The JobWatch invoice, credit note, or purchase order can only be printed from JobWatch.

Q: I have completed a job for a site, but I want to invoice the parent contact.  How does this work?

A: The site contact record must be linked to a valid parent contact (a contact record that has a valid account reference).  Once synchronised, the invoice will be created against the site contact, but the invoice will be posted to the parent contact record in Xero.  

Q: Do tracking categories populate the department code field in JobWatch?

A: No.  When switching to a Xero integration, the department field is no longer visible in JobWatch.  The tracking categories are stored in two separate fields in the user interface.  Users will not have access to modify their contents.  Additional tracking categories will need to be imported through the user interface.

Q: I cannot add nominal or tax codes, why?

A: When synchronising with Xero, the functions to add tax and nominal codes are controlled by the import options in the user interface.  This creates a link between the two systems.  Any new nominal or tax codes must be imported via the user interface.

Q: What happens if something goes wrong.  How will I know?

A: Sometimes things do go wrong.  Whenever an issue occurs, a contact note is created for the error.  The contact note subject refers to the type of error.  For example; where an invoice has an incorrect tax type, a contact note type with the subject Invoice Error will show a dialogue entry explaining which invoice failed and why?

Q: Is a contact note created each time an error occurs?

A: A contact note is created for a contact where no contact note exists for the type of error or the contact note for a previous error has already been marked as completed. Where there is an open contact note for the type of error, the dialogue box is updated with the new error message.

Email This Post Email This Post
Updated on 12th April 2021

Related Articles