fmAccounting Link (MYOB AccountRight Edition) v2 Integration Guide
These instructions demonstrate how to replicate the FileMaker MYOB AccountRight integration from the fmAccounting Link (MYOB AccountRight Edition) v2 solution file in your existing FileMaker solution. There are a number of ways to integrate the fmAccounting Link file with your existing FileMaker solution which are outlined in our FAQ section here.
The fmAccounting Link (MYOB AccountRight Edition) currently includes the following examples:
- authentication with the MYOB API (Desktop and Cloud versions)
- download Chart of Accounts from AccountRight to FileMaker
- download Tax Codes from AccountRight to FileMaker
- download Categories from AccountRight to FileMaker
- download Contacts from AccountRight to FileMaker
- upload Contacts from FileMaker to AccountRight
- download Inventory Items from AccountRight to FileMaker
- download Invoices from AccountRight
- upload Invoices from FileMaker to AccountRight
- upload Payments from FileMaker to AccountRight
- download Purchase Orders from AccountRight
- upload Purchase Orders from FileMaker to AccountRight
- download Bills from AccountRight
- upload Bills from FileMaker to AccountRight
- download Jobs from AccountRight
- upload Jobs from FileMaker to AccountRight
- download Job Budgets from AccountRight
- upload (update existing) Job Budgets from FileMaker to AccountRight
- download General Journals from AccountRight to FileMaker
- upload General Journals FileMaker to AccountRight
- download Employees from AccountRight
- upload Employees to AccountRight
- download Sale Orders from AccountRight
- upload Sale Orders from FileMaker to AccountRight
- download Supplier Payments from AccountRight
- upload Supplier Payments from FileMaker to AccountRight
- download Inventory Adjustments from AccountRight
- upload Inventory Adjustments from FileMaker to AccountRight
- download Inventory Item Price Matrix (Custom Price Levels) from AccountRight
- update Inventory Item Price Matrix (Custom Price Levels) from FileMaker to AccountRight
- download Timesheets from AccountRight
- upload Timesheets to AccountRight
- download Payroll Categories from AccountRight
We are continually updating the fmAccounting Link files to include additional examples. If you would like to see an example for other AccountRight endpoints supported by the AccountRight API please let us know.
MYOB AccountRight Live is a hybrid product, this means that the data the API allows you to access and work with, can live either on the users computer (local computer or one on a network in their office) or it can live in the MYOB Cloud.
If you are working on a local computer or network server we recommend using the example Clearwater Pty Ltd company files that are installed as part of MYOB AccountRight. If you are working in the MYOB Cloud then you will be able to get access to the Sandbox company file that you can use for testing.
Important: please ensure you have made a backup of your production MYOB Company File/s in case you need to revert to a backup copy.
Once you have a happy with the integration you can switch over to using the actual AccountRight Company file.
To setup your copy of fmAccounting Link (MYOB AccountRight Edition) with either the MYOB Cloud or Desktop versions of AccountRight please read the instructions for these in our Trial Version Setup Guide.
You should be comfortable with uploading and downloading data between FileMaker and AccountRight. You can view each of the scripts in the Script Debugger as you go to see what steps are being taken – we have commented the scripts to explain each step of the process. You are now ready to tackle the integration with your own FileMaker solution.
Make sure you check out our fmAccounting Link file videos – we will be adding more videos in the coming months that demonstrate each of the modules in the fmAccounting Link file.
N.B. as we are continually updating the fmAccounting Link file the screenshots below might not look exactly the same as what you see. Please refer to your fmAccounting Link file for the latest version of these.
When embedding/recreating functionality from the fmAccounting Link file in your existing FileMaker solution you only need to bring across the functionality for the features you require. For example if you just need to be able to upload Contacts, Invoices and Customer Payments from FileMaker to AccountRight you just need to bring across the relevant tables, scripts etc for these features. You might also need to bring across the ability to download the Chart of Accounts and Tax Codes if you need to specify these dynamically rather than hardcoding these. You will also need to bring across the relevant authentication components for either the Cloud API or the Desktop API.
Don't forget you will also need to seed any existing Contact (Customer/Supplier) records with their MYOB ID if they already existing in both your FileMaker solution and AccountRight. See our FAQ guide for further details here.
Cloud API Authentication Keys
If your MYOB file is hosted in the MYOB Cloud when it comes to integrating the authentication into your existing FileMaker solution you will need to copy these 2 fields from the Interface table:
as well as the values contained in those fields (they are the Developer API keys for the fmAccounting Link (MYOB AccountRight Edition) solution). You can find these fields on the DEV Interface layout. You can always create your own set of Developer API keys by applying in the MYOB Developer Centre.
Step 1: Custom Functions – Copy and Paste or Import
This requires FileMaker Pro Advanced – you can either copy the Custom Functions from the fmAccounting Link file or you can import them into your solution file.
N.B. since the release of FileMaker Pro v17 there are no longer 2 separate applications (FileMaker Pro and FileMaker Pro Advanced). FileMaker Pro v17 or later now includes the advanced tools found previously in the FileMaker Pro Advanced Application - you can can enable these in the FileMaker Pro preferences.
If you already have any of these custom functions installed you can skip those:
Step 2: Tables – Copy and Paste or Import
This requires FileMaker Pro Advanced – you can either copy the Tables from the fmAccounting Link file or you can import them from your solution file:
Depending on your integration and your existing solution file won’t need to import all of the following tables if you already have an existing matching table:
Accounts: this stores the AccountRight Chart of Accounts records – if you already have a Chart of Accounts table you won’t need to import this
Addresses: this stores the Contact address records – if you already have a Contact Addresses table or store your Addresses in your Contacts table you won’t need to import this
Alphabet: this is used for Identifiers where you can associate letters from A-Z against a Contact
BankAccounts: this is used for the Employee Payment Details
Bills: this stores the Bills records – if you already have a Bills table you won’t need to import this
BillItems: if you already have a Bill Items (Bill Line Items) table you won’t need to import this
CalculateSalesTaxTerms: this is used for the value list of possible Sales Tax calculation from selections for Item records
Categories: this stores the Categories records from MYOB
Company Files: this stores a record for each Company File that is available to authenticate with. You then select which of these Company Files you wish to use when making API requests
Contacts: this stores the Contact records (Customers and Suppliers) – if you already have a Contacts table you won’t need to import this
Countries: this stores the Country records – if you already have a Countries table or all your Contacts and transactions are restricted to just a single Country you won’t need to import this
CustomPriceLevels: this stores the custom price levels for the related Inventory Item
DeliveryStatuses: this stores the list of delivery status options
Employees – this stores the Employees records – if you already have a Employees table you won’t need to import this
FormTemplates: this stores the list of Form Templates that you can download from MYOB
GeneralJournals: this stores the General Journals records – if you already have a General Journals table you won’t need to import this
GeneralJournalItems: if you already have a General Journals Items (General Journals Line Items) table you won’t need to import this
Identifiers – this stores the Contact Identifier selections
Interface: this is ‘Preferences’ or ‘Settings’ table that contains a single record. If you already have a single record Preferences table you can use that. N.B. if you are connecting to the MYOB Cloud API you will need the APIKey and APISecret fields and to copy/paste the values for these from the fmAccounting Link file into your solution.
InventoryAdjustments: this stores the Inventory Adjustments records – if you already have an Inventory Adjustments Journals table you won’t need to import this
InventoryAdjustmentItems: if you already have a Inventory Adjustments Items (Inventory Adjustments Line Items) table you won’t need to import this
Invoices: this stores the Invoice records – if you already have a Invoices table you won’t need to import this
InvoiceItems: if you already have a Invoice Items (Invoice Line Items) table you won’t need to import this
Items: this stores the Inventory Item records – if you already have a Products/Price List/Inventory Items table you won’t need to import this
Jobs: this stores the Jobs records - if you already have a Jobs table you won’t need to import this
JobBudgets: this stores the list of Job Budgets related to the parent Job
Navigation: this is part of the fmAccounting Link demo file and usually will not be required
Orders: this stores the Orders records – if you already have an Orders table you won’t need to import this
OrderItems: if you already have a Orders Items (Orders Line Items) table you won’t need to import this
Payments: this stores the Customer Payments records (Payments for an Invoice/Order) – if you already have a Payments table you won’t need to import this
PaymentItems: this stores the individual line items for a Customer Payment record
PaymentTerms: this is used for the value list of possible Payment Terms
PayrollCategories: this stores the list of Payroll Categories that you can download from MYOB - if you already have a Payroll Categories table you won’t need to import this
PurchaseOrders: this stores the Purchase Order records – if you already have a Purchase Orders table you won’t need to import this
PurchaseOrderItems: if you already have a Purchase Order Items (Purchase Order Line Items) table you won’t need to import this
ServerSideErrors: this stores records that are generated by the server side scripts when they encounter an error or you use the debugging log feature
TaxCodes – this stores the Tax Codes records – if you already have a Tax Codes table you won’t need to import this
Timesheets: this stores the Timesheet records – if you already have a Timesheet table you won’t need to import this
TimesheetLines: if you already have a Timesheet Lines table you won’t need to import this
TimesheetLineEntries: if you already have a Timesheet Line Entries Lines table you won’t need to import this
Step 3: Create Fields in Existing Tables
If you already have existing tables for Contacts, Invoices, InvoiceItems, Payments, PaymentItems, Products, Interface etc you will simply need to create the required additional fields in each of the tables if you are not going to import these tables. If you have FileMaker Pro Advanced you can use that to copy/paste the fields from the fmAccounting Link (MYOB AccountRight Edition) solution file.
Please also note the following special fields that you will need in each table that you are downloading data into and uploading data from:
_kf_MYOB_ID: each table that you download data into or upload data from will require one of these fields (e.g. _kf_MYOBAccountID, _kf_MYOBContactID and _kf_MYOBInvoiceID). These fields store the MYOB AccountRight ID (equivalent to a FileMaker Primary Key field/auto enter serial number/UUID). This allows us to update records if we detect the presence of a value in these fields, rather than creating a new record each time in AccountRight
RowVersion – this stores a numeric value that changes upon a record update and is generated by AccountRight. You must pass the latest RowVersion value to the MYOB API when updating an existing record in MYOB (e.g. updating a Contact or Invoice).
LastAPIResult – this stores the last API request result for the current record (e.g. in Contacts, Invoices, Payments etc). It doesn’t need to be displayed on a user visible layout but it helpful to see the response from AccountRight API when troubleshooting API requests
Step 4: Relationship Graph – Table Occurrences and Relationships
You will need to recreate the Table Occurrences and Relationships from the fmAccounting Link file in your solution file. Unfortunately FileMaker Pro/Advanced does not currently support copy/pasting or importing of table occurrences and relationships so these will need to be recreated manually. As with importing tables if you did not import certain tables you will not need to recreate table occurrences/relationships associated with those tables you did not import:
Step 5: Create Layouts
You will need to create any necessary layouts in your solution file with the same names as the fmAccounting Link file. If you did not import certain tables then you will not need to create layouts for those tables. At this step you are only creating the blank Layouts with the same name as in fmAccounting Link. You will be copy/pasting the layout objects/content at a later step. As we have not imported any scripts yet copy/pasting layout content would mean any buttons that reference scripts will be broken.
If you already have existing layouts for tables that you did not need to import (e.g. you already have layouts for viewing Contacts, Invoices etc) then you don't need to create new versions of these. You will simply be adding your new fields created at Step 3 and adding buttons to perform the relevant scripts later on.
As you will be recreating layouts in your existing solution file we will be assuming that you will with to recreate the layouts using the same theme/style as your existing solution and not necessarily keep the layouts the same as they are in the fmAccounting Link file. The layouts in the fmAccounting Link file use the Cool Gray theme.
The “DEV” layouts are layouts designed for the developer and are kept hidden from users.
We find having the Manage Layouts window open for both the fmAccounting Link file and your solution file side by side is the quickest way to create new layouts in your solution file. You can quickly copy the Layout Name from the fmAccounting Link file, create a new Layout in your solution file and paste in the name and then select the correct table occurrence to use in the Show Records from menu.
Step 6: Scripts – Copy and Paste or Import
You can use FileMaker Pro/Pro Advanced to either copy/paste or import the scripts from the fmAccounting Link file. You should import all scripts in the folders that you are integrating with (e.g. Contacts, Items, Invoices etc). You will generally need to import these script folders as they related to authentication and retrieving the list of company files to connect to:
MYOB Company File
You can generally not import scripts in the following folders as they are used in the fmAccounting Link demo file and usually not required for your solution file:
N.B. some of the scripts perform other scripts which include script parameters which are referenced by the calling script. If you are creating these scripts yourself make sure you include the script parameters. We use the native FileMaker JSON functions for passing script parameters. You can change this to your preferred method for passing multiple script parameters as required.
You can check each script for any problems when viewing a script by right-clicking the tab in the script editing pane and choose Check for Problems - errors are highlighted:
You can also use a FileMaker developer tool like BaseElements or FMPerception to check for any errors with your integration when you've completed all the steps.
Step 7: Value Lists
You can use FileMaker Pro/Pro Advanced to copy/paste the Value Lists from the fmAccounting Link file in your solution file.
Step 8: Layout Contents – Copy and Paste Layout Objects/Content
Now that we have the necessary value lists and scripts in your solution file you can now copy/paste the Layout objects/content from the layouts in the fmAccounting Link file. You will first need to size the layouts and layout parts to the correct sizes, or you can customise these to suit your requirements. We are assuming that you will be changing the layouts to match your existing theme and styles, but whilst you are testing the integration you can copy/paste these “as is” and once everything is working you can then come back and restyle the layouts to suit your requirements.
if you didn't need to create new layouts (e.g. you already have layouts for viewing Contacts, Invoices etc) then you can simply copy/paste the new fields and buttons across.
Step 9: AccountRight API Authentication
You are now ready to start testing your integration. The first step is to ensure you can authenticate successfully with the AccountRight API. You need to recreate the functionality to authenticate with either the Desktop API or the Cloud API in your solution file. Once you have successfully authenticated you can move on to the additional modules and test the scripts that you have imported to ensure they are working as expected. We recommend testing in the following order:
- Tax Codes
then any additional modules you have recreated.
Once you can successfully download and upload using the scripts/buttons that you have imported you are ready to go live. We recommend using a FileMaker developer tool like BaseElements or FMPerception to check for any errors with your integration at this stage and resolve these first.
Step 14: Go Live and switch from Sandbox/Clearwater Company to your live Company File
Once you have successfully tested the integration of your FileMaker solution file with the AccountRight API you can then select your live MYOB AccountRight Company File.