fmAccounting Link (MYOB Essentials Edition) v2 Integration Guide

These instructions demonstrate how to replicate the FileMaker MYOB Essentials integration from the fmAccounting Link (MYOB Essentials 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 Essentials Edition) currently includes the following examples:

  • authentication with the MYOB API
  • download Chart of Accounts from Essentials to FileMaker
  • download Tax Codes from Essentials to FileMaker
  • download Contacts from Essentials to FileMaker
  • upload Contacts from FileMaker to Essentials
  • download Inventory Items from Essentials to FileMaker
  • download Invoices from Essentials
  • upload Invoices from FileMaker to Essentials
  • upload Payments from FileMaker to Essentials
  • download Bills from Essentials
  • upload Bills from FileMaker to Essentials
  • download Jobs from Essentials
  • upload Jobs from FileMaker to Essentials
  • download General Journals from Essentials to FileMaker
  • upload General Journals FileMaker to Essentials
  • download Employees from Essentials
  • upload Employees to Essentials
  • download Supplier Payments from Essentials
  • upload Supplier Payments from FileMaker to Essentials
  • download Timesheets from Essentials
  • upload Timesheets to Essentials
  • download Payroll Categories from Essentials

We are continually updating the fmAccounting Link files to include additional examples. If you would like to see an example for other Essentials endpoints supported by the Essentials API please let us know.

To setup your copy of fmAccounting Link (MYOB Essentials Edition) please read the instructions for these in our Trial Version Setup Guide.

You should be comfortable with uploading and downloading data between FileMaker and Essentials. 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 Essentials 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 authenticating with MYOB Essentials.

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 Essentials. See our FAQ guide for further details here.

Cloud API Authentication Keys

When it comes to integrating the authentication into your existing FileMaker solution you will need to copy these 2 fields from the Interface table:

APIKey 
APISecret

as well as the values contained in those fields (they are the Developer API keys for the fmAccounting Link (MYOB Essentials 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 Essentials 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

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

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

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

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. You will need the APIKey and APISecret fields and to copy/paste the values for these from the fmAccounting Link file into your solution.

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

Navigation: this is part of the fmAccounting Link demo file and usually will not be required

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 Essentials 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 Essentials 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 Essentials

RowVersion – this stores a numeric value that changes upon a record update and is generated by Essentials. 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 Essentials 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

Authentication

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:

System

Developer

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: Essentials API Authentication

You are now ready to start testing your integration. The first step is to ensure you can authenticate successfully with the Essentials API. You need to recreate the functionality to authenticate with the MYOB Essentials 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:

  1. Accounts
  2. Tax Codes
  3. Items
  4. Contacts
  5. Invoices
  6. Payments

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/Test Company to your live Company File

Once you have successfully tested the integration of your FileMaker solution file with the Essentials API you can then select your live MYOB Essentials Company File if you were using a Sandbox/test company file.

Still need help? Contact Us Contact Us