|
|
| (2 intermediate revisions by 2 users not shown) |
| Line 1: |
Line 1: |
| − | {{DISPLAYTITLE:Xero Integration}}
| + | =This Content Has Moved House= |
| − | = Overview = | |
| − | Emersion integrates seamlessly with the Xero Billing Platform found at www.xero.com.
| |
| | | | |
| − | Emersion and Xero features:
| + | This article has been moved to our new home for documentation and help content, the new Emersion Knowledge Base. |
| − | * Linking Emersion Accounts with Xero Contacts
| |
| − | * Synchronizing invoices created in Emersion with Xero.
| |
| − | * Breaking down of ledger card lines within Emersion by ledger code
| |
| − | * Receiving payments and credit notes from Xero and reflecting them in Emersion
| |
| − | * Pushing payments received in Emersion to Xero
| |
| − | <br />
| |
| | | | |
| − | Before you can configure the Xero Emersion integration, you are required to have the feature enabled on your service provider account. Please contact [mailto:sales@emersion.com.au sales@emersion.com.au] if you are interested in this feature.
| + | We are sorry for the untidiness while we are shifting locations and we appreciate your patience during the transition to our new home. |
| | | | |
| − | You will know when the Xero integration is enabled when you have access to '''Admin > Xero'''. Please also ensure you follow the First Time Setup guidelines below.
| + | [https://resources.emersion.com/display/EKB/Xero Take me to the new articles] |
| | | | |
| − | Note: Only a single Xero Company can be linked to the Emersion platform.
| + | [[file:new_home_sm.jpg|900px]] |
| − | | |
| − | == First Time Setup ==
| |
| − | {| style="color: black; background-color: #ffffcc;
| |
| − | |You have had the Xero Integration module activated and would like to know how to initially configure Emersion to integrate with Xero. Apart from watching the short video below, the basic steps for you to now complete are as follows:
| |
| − | | |
| − | 1) Nav: '''Admin > Xero''' <br />
| |
| − | * On this page, link your Xero company to Emersion by clicking on the '''Connect to Xero''' button and following the on-screen prompts. With a connection is established, users can add the default bank account.
| |
| − | | |
| − | 2) Nav: '''Admin > Xero > Xero Payments'''<br />
| |
| − | On this page:
| |
| − | | |
| − | * Set a default Bank Account. This will be used as a default/fallback bank account for payment transactions that do not specifically have a mapping as per the following step;
| |
| − | * If appropriate, create a payment mapping between alternate Xero bank accounts and Emersion's payment methods. Once this is done, the user can move into mapping Emersion's ledger codes with Xero's account codes.
| |
| − | | |
| − | 3) Nav: '''Admin > Ledger Mapping'''<br />
| |
| − | * On this page, users can map Emersion ledger codes to Xero account codes. This step is optional but recommended - at least for common ledger codes like PACKAGE_PLAN_ACCESS_FEE_ADV, CARRIER_PRODUCT_USAGE, etc.
| |
| − | * You may wish to utilise our bulk upload tool for mapping many ledger codes at once. See [https://resources.emersion.com/display/EKB/Ledger+Code+Mapping+with+Xero+Integration this article for instructions.]
| |
| − | | |
| − | '''! IMPORTANT !''' By default, Emersion's ledger codes will map to Xero's default revenue code 200 "Sales". For this reason, Emersion strongly advises not to archive or delete this code.
| |
| − | | |
| − | 4) Nav: '''Customer > Detail > Xero Integration ''' <br />
| |
| − | * It is absolutely imperative that you link an Emersion Account to a Xero Contact. Firstly click the refresh button to update our cache with a fresh list of contacts directly from your Xero instance, then DOUBLE-click the input box to load the list. You can start typing a name to search this list.
| |
| − | * This step must be performed for any existing accounts you wish to sync to Xero.
| |
| − | |}
| |
| − | | |
| − | == Overview of Supported and Non Supported Transactions ==
| |
| − | | |
| − | '''Supported Transactions'''
| |
| − | <br />
| |
| − | a) We only push across payments once allocated to an invoice, and positive balance invoices to Xero.
| |
| − | <br />
| |
| − | b) We only pull payments and credits from Xero to Emersion, provided they apply to invoices that have come across from Emersion to Xero in the first instance.
| |
| − | <br />
| |
| − | <br />
| |
| − | '''Non Supported Transactions'''
| |
| − | <br />
| |
| − | a) Refunds do not go from Emersion to Xero.
| |
| − | <br />
| |
| − | b) Debit Write offs and normal Write Offs do not go from Emersion to Xero.
| |
| − | <br />
| |
| − | c) Credits applied to invoices in Emersion do not go across to Xero (Note: Credits coming from the other direction - Xero to Emersion will work).
| |
| − | <br />
| |
| − | d) Invoices in credit balance do not go across to Xero, however, once the credit is converted to a payment and applied to the next invoice, the resulting Payment will go to Xero.
| |
| − | <br />
| |
| − | f) Transactions reversing or voiding Payments in Xero are not reflected in Emersion.
| |
| − | <br />
| |
| − | g) Transactions reversing or voiding Credits are not reflected in Emersion.
| |
| − | <br />
| |
| − | h) Any kind of general credit or debit adjustment made in Xero does not go across to Emersion.
| |
| − | <br />
| |
| − | i) Deleting or modifying any invoice or payment does not go across to from Xero to Emersion.
| |
| − | <br />
| |
| − | <br />
| |
| − | <br />
| |
| − | Additionally, transactions are only synced as far as a month prior in terms of transactions going to Xero or from Xero.
| |
| − | | |
| − | == Credits ==
| |
| − | Do not use the [[Credits|Credit]] feature in Emersion to create a credit if your service provider subscribes to this module. Emersion only supports pulling credit notes from Xero into Emersion. Credit notes in Xero are saved as credits in Emersion. However this synchronisation is one-way. If an Emersion credit ''and'' a Xero credit is created for the same transaction, users will see two credits appearing in Emersion.
| |
| − | | |
| − | Additionally, De-allocating a credit from an invoice in Xero will not change anything in Emersion. This is also true if you then Void the credit note in Xero. Performing these actions will most likely cause your Xero account & linked Emersion account to not balance.
| |
| − | | |
| − | == Configuration of Xero and Emersion ==
| |
| − | Watch the training video to:
| |
| − | | |
| − | * Learn how to connect to Xero from Emersion
| |
| − | * Set your default payment method to go to your nominated bank accounts in Xero
| |
| − | * Map Ledger codes against Xero accounts
| |
| − | * Associate Emersion 'accounts' with Xero 'contacts'
| |
| − | | |
| − | <mediaplayer MWPlayerConfig="MyCustomConfig" height="400" width="600">https://wiki.emersion.com/wiki/media/xero-integration.mp4</mediaplayer>
| |
| − | <br />
| |
| − | | |
| − | == Synchronisation with Accounts ==
| |
| − | | |
| − | Customer accounts in Emersion need to be linked to contacts in Xero. We do not currently support creating a Xero contact through integration.
| |
| − | | |
| − | You can ''link'' an Emersion Account to a Xero Contact by utilizing one of the following methods;
| |
| − | | |
| − | == Creating a new Customer ==
| |
| − | When you create a new customer in Emersion, first screen in the wizard includes a '''Xero Account Name''' field. Use the drop-down to select which account to link to this new customer. This will perform an integration request to your Xero instance and pull a list of active contacts. The contact you wish to link to must already have been created in Xero.
| |
| − | | |
| − | [[File:xero-create-customer.png|border|The Create Customer Wizard showing Xero fields]]
| |
| − | | |
| − | == Updating Existing Account ==
| |
| − | To do this;
| |
| − | Nav: [[Account_Management/Customer_Screen/Details#Xero_Integration|'''Customer > Detail > Xero Integration''']]. Click the link to go to this page's help page.
| |
| − | | |
| − | == Mapping Ledger Codes ==
| |
| − | | |
| − | An important aspect of integration to accounting platforms like Xero is the ability to map Emersion ledger codes to Xero ledger codes so as to keep your accounting as simple or as complex as you like and to ensure both systems reflect how you receive revenue from your customers.
| |
| − | | |
| − | All Emersion card lines (line items) are broken down into ledger codes. These codes are designed to categorize charges into granular groups and break up different forms of revenue.
| |
| − | | |
| − | Where Emersion integrates with various accounting platforms, we allow the mapping of our ledger codes with those setup within your Xero account.
| |
| − | | |
| − | To begin mapping ledger codes, you need to log into the Emersion system and then follow the steps below:
| |
| − | | |
| − | # Navigate to Admin > Xero > Xero Ledger Map (''tab'')
| |
| − | # Once the page has loaded, you will see a list of ledger codes that are currently available to you under your Emersion account.
| |
| − | # Click on the name of the Emersion ledger code
| |
| − | # Select a ledger code from the drop down list of available ledger codes that have been retrieved from your Xero account.
| |
| − | # You may enter a description of this mapping (''optional'')
| |
| − | # Click the Save Mapping button
| |
| − | | |
| − | It is possible to map multiple different Emersion ledger codes to a single Xero ledger code, or you may choose to be very granular and have an individual Emersion <> Xero ledger code mapping for every single code.
| |
| − | | |
| − | {| class="wikitable"
| |
| − | |-
| |
| − | | Emersion also have a bulk import tool available for you to import & map multiple Xero ledger codes. See [[Data_Import/Xero_Ledger_Code_Mapping|Xero Ledger Code Mapping - Bulk Import]]
| |
| − | |}
| |
| − | <br />
| |
| − | | |
| − | == Default Xero Ledger Code (200) ==
| |
| − | | |
| − | A very important note on Emersion <> Xero ledger code mapping relates to the scenario where an individual card line whose Emersion ledger code has not been mapped to a Xero ledger code needs to ''fall back'' to a default ledger code.
| |
| − | | |
| − | When we attempt to push (approved) invoice card lines across to your Xero account, we will assign these card lines to default Xero revenue code 200.
| |
| − | | |
| − | * If this code does not exist, has been delete or archived, or has been changed to an account type other than revenue, invoice card lines will fail to push to Xero and you may continue to see an invoice in Xero as $0 & in a Draft status.
| |
| − | | |
| − | In a brand new setup of Xero, there is a default revenue account code '''200''' with the name '''Sales'''.
| |
| − | | |
| − | '''Please do not delete, archive, or make this account code anything other than type revenue. This is the default fallback for un-mapped ledger codes.'''
| |
| − | | |
| − | [[File:Xero-revenue-200.png|border|Xero Default Revenue Account Code 200 - Sales]]
| |
| − | | |
| − | Further information on how to configure you Chart of Accounts in Xero can be found at https://help.xero.com/au/Settings_ChartofAccounts
| |
| − | | |
| − | <br />
| |
| − | | |
| − | == Xero Pollers ==
| |
| − | * There are 4 ''pollers'' that handle Xero integration automatically. The frequency of these pollers are as follows;
| |
| − | {| class="wikitable"
| |
| − | |-
| |
| − | ! Poller !! Action(s) !! Schedule !! Notes
| |
| − | |-
| |
| − | | Push Completed Invoices || When an Emersion invoice is Approved, this poller will attempt to send all the card lines to the linked Xero invoice - and further mark it Authorised (and ready for payment) || Every 15 minutes || Must not have already been pushed. Must be ''Approved''. Xero invoice must still be in ''Draft'' status and exist. Card lines will need to either have ledger codes mapped, or the [[#Default_Xero_Ledger_Code_.28200.29|default Xero account code ''200'']] must exist as a fallback. Total invoice amount must be greater than $0 (zero) dollars. Whilst an initial invoice may be reserved in Xero, we will not push any cardlines for an invoice that totals less than $0 (ie. a "credit invoice").
| |
| − | |-
| |
| − | | Check For Credit Notes || Credit notes created in Xero, will be pulled across and processed as a credit in the ledger || Every 15 minutes || No greater than 30 days ago. Must not already exist in Emersion. Must be attached to an existing (linked) invoice. Must be status ''Paid''.
| |
| − | |-
| |
| − | | Push New Payments || Payments made in Emersion will be pushed and applied to the linked invoice in Xero || Every 1 Hour || Must be made against linked invoice(s). Must not have already been processed. Only payments against invoices are supported. (ie. Not Ledger Credits or Debits)
| |
| − | |-
| |
| − | | Check For Payments || Payments created in Xero against linked Emersion invoices will be pulled across and applied to the invoice in Emersion || Every 1 Hour || No greater than 30 days ago. Must not already exist in Emersion. Must be attached to an existing (linked) invoice. Must be ''Authorised''. Payment amount must be less than the invoice outstanding amount.
| |
| − | |}
| |
| − | | |
| − | * Only transactions that are payments against existing invoices will be pushed to Xero. No '''credit''' or '''debit''' ledger transactions will be pushed.
| |
| − | | |
| − | * Only credit notes that have allocated amounts against already linked invoices will be pulled from Xero. The credit note must also be in status ''Paid''.
| |
| − | | |
| − | * If a payment made in Xero also creates an '''overpayment''', then we will not pull the overpayment amount from Xero - only the allocated payment amount against an already linked invoice.
| |
| − | | |
| − | * If an overpayment amount in Xero is then allocated to an outstanding invoice, we will NOT pull this information in to Emersion
| |
| − | | |
| − | * If a Xero created payment is applied to a Xero invoice as a result of an "[https://help.xero.com/au/BankAccounts-Reconciliation-AcceptMatch automatic reconcile match]" before a matching payment from Emersion has been pushed, the Emersion payment will continue to attempt to push to Xero and will never complete (<span title="Failed pushing payment allocated against Invoice #123456 to Xero due to: Validation Error (Payments can only be made against Authorised documents, Payment amount exceeds the amount outstanding on this document)">''hover over me for sample error''</span>). <br />
| |
| − | Emersion recommend you do not allow automatic reconciliation matches against invoices unless an Emersion initiated payment is the target of the match (as indicated by by [https://go.xero.com/common/images/icon-banktransfer-a3df40bc03255229137fe3ba3ef04b0f.gif double arrow icon]).
| |
| − | | |
| − | == Xero Bulk Actions ==
| |
| − | | |
| − | You may wish to bring forward one or more of the "poller" processes manually rather than wait for the scheduled processing time.
| |
| − | | |
| − | * '''Nav:''' Admin > Xero > Xero Bulk Actions
| |
| − | * Simply click on the appropriate process you wish to action. You may choose from;
| |
| − | ** Push Pending Payments to Xero (''the page will dynamically determine of any invoices are valid and can be pushed'')
| |
| − | ** Pull Payments from Xero
| |
| − | ** Pull Credits from Xero
| |
| − | ** Push Completed Invoices to Xero (''the page will dynamically determine of any payments are valid and can be pushed'')
| |
| − | | |
| − | [[File:Xero bulk actions 001.png|800px]]
| |
| − | | |
| − | == Xero / Emersion Ledger Transaction ==
| |
| − | | |
| − | The following screenshots represent an Approved invoice that has been pushed to Xero (and set to status 'Awaiting Payment'). <br/>
| |
| − | | |
| − | For the purpose of showing an example between Emersion & Xero, the following numbers represent different methods of individual transactions:<br/>
| |
| − | | |
| − | * <u>('''1''') Represents a payment made in Xero and applied to the linked invoice.</u> <br/>
| |
| − | | |
| − | Our '''Check For Payments''' poller has then picked this up and ''pulled this payment into Emersion'' and allocated the amount to the linked invoice. <br/>
| |
| − | | |
| − | In the screenshots below, you can see this payment represented in both the Payments tab, as well as the Transactions tab of a customer account. <br/>
| |
| − | | |
| − | Note the ''Transaction Reference'' on the Payment tab and the ''Reference'' on the Transaction tab represent the Xero [https://en.wikipedia.org/wiki/Universally_unique_identifier GUID] of the the payment transaction within Xero. Once logged into Xero, you can view the direct payment by modifying the URL. For example: <nowiki>https://go.xero.com/Bank/ViewTransaction.aspx?bankTransactionID=21abb5e5-e978-4de7-b44e-83d686749ba5</nowiki> - where ''21abb5e5-e978-4de7-b44e-83d686749ba5'' is the reference taken from either the Payment or Transaction tab in Emersion.
| |
| − | | |
| − | * <u>('''2''') Represents a Payment made in Emersion and applied to the linked invoice.</u> <br/>
| |
| − | | |
| − | Our '''Push New Payments''' poller has picked this up and pushed it to Xero and allocated it to the linked invoice. <br/>
| |
| − | | |
| − | This particular payment in Emersion will have a reference as entered by you when creating the payment (''this is sometimes a system generated reference in the case of automated payments via a payment gateway'') and will push to Xero with a payment reference that references both the (Emersion) Payment ID and the (Emersion) journal ID of the '''unallocateUnallocatedPayment''' transaction type in the customer ledger journal (''Transactions''). For example: ''Payment received in Emersion [Journal #9100699, Payment #2081312]''
| |
| − | | |
| − | * <u>('''3''') Represents a '''Credit Note''' that has been created in Xero and applied to the linked invoice.</u> <br/>
| |
| − | | |
| − | (Whilst Emersion does not have a concept of a Credit Note per se, we support a '''Credit''' transaction type.) <br/>
| |
| − | | |
| − | Our '''Check For Credit Notes Poller''' has picked up the Credit Note from Xero and applied it to the linked invoice & the customer account in Emersion. This is not a payment, but will be represented as a '''credit''' transaction type in the ledger journal (''Transactions''). <br/>
| |
| − | | |
| − | Note the ''Reference'' on the Transaction tab represent the Xero [https://en.wikipedia.org/wiki/Universally_unique_identifier GUID] of the the credit note within Xero. Just like payments, you can view the direct credit note by modifying the URL. For example: <nowiki>https://go.xero.com/AccountsReceivable/ViewCreditNote.aspx?creditNoteID=e2c84d1f-6f2d-4809-a8f4-1e94e7910718</nowiki> - where ''e2c84d1f-6f2d-4809-a8f4-1e94e7910718'' is the reference taken from the credit transaction in the customer ledger journal (''Transactions'') in Emersion.
| |
| − | <!--
| |
| − | [[File:Xero sample 001.png|thumbnail|Xero Invoice View]] <br/>
| |
| − | [[File:Xero_sample_002.png|thumbnail|Emersion Transactions View]] <br/>
| |
| − | [[File:Xero_sample_003.png|thumbnail|Emersion Payments View]]
| |
| − | -->
| |
| − | | |
| − | <gallery>
| |
| − | File:Xero_sample_001.png|Xero Invoice View
| |
| − | File:Xero_sample_002.png|Emersion Transactions View
| |
| − | File:Xero_sample_003.png|Emersion Payments View
| |
| − | </gallery>
| |
| − | | |
| − | == Related Reports ==
| |
| − | | |
| − | The report '''Xero Integration Errors''' (id: 1063) is included with this module. It can be found under '''Report > List > Finance'''. It is advised you run this report on a regular basis to confirm the transactions are successfully syncing. <br />
| |
| − | Further info on this report: [[Integrations/Xero/Troubleshooting#Xero_Integration_Errors_Report Xero Integration Errors Report]]
| |
| − | | |
| − | == Troubleshooting Issues with Xero Integration ==
| |
| − | This section has it's own page --> [[Integrations/Xero/Troubleshooting|Toubleshooting Issues with Xero Integration]]
| |
| − | | |
| − | =See Also=
| |
This article has been moved to our new home for documentation and help content, the new Emersion Knowledge Base.
We are sorry for the untidiness while we are shifting locations and we appreciate your patience during the transition to our new home.
