Integration - Embedding

These instructions describe at a high level how to replicate the functionality of the fmAccounting Link (QuickBooks Online Edition) solution in your existing FileMaker solution. The fmAccounting Link (QuickBooks Online Edition) solution currently includes the following examples for the following QuickBooks Online API endpoints:

• Company Info: authenticate with a single QuickBooks Online company and download company information
• Customers: download and upload Customers
• Vendors: download and upload Vendors (Suppliers)
• Invoices: download and upload Invoices
• Estimates: download and upload Estimates (Quotes)
• Bills: download and upload Bills
• Purchase Orders: download and upload Purchase Orders
• Items: download and upload Items (Products)
• Payments: download and upload Payments against an Invoice
• Attachments: download and upload attachments for Invoices, Estimates, Bills, Purchase Orders, Customers and Vendors
• Notes: download and upload notes for Invoices, Estimates, Bills, Purchase Orders, Customers and Vendors
• Download Account Codes, Tax Rates, Tax Codes, Classes, Departments, Customers Types, Payment Methods, Terms and Preferences

N.B. as we are continually updating the fmAccounting Link (QuickBooks Online Edition) 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.

You can find more information about authenticating with QuickBooks Online in our trial setup guide here. We recommend using a free QuickBooks Online Sandbox Company instead of your actual live QuickBooks Online Company when testing, especially if you plan to test uploading data from FileMaker to QuickBooks Online (e.g. creating Contacts, Invoices, Payments etc). This allows you to test out the fmAccounting Link trial without having to worry about adding transactions and deleting them from your live QuickBooks Online Company.

Step 1: Custom Functions – Copy and Paste or Import

You can either copy the Custom Functions from the fmAccounting Link file or you can import them into your solution file. If you already have any of these custom functions installed you can skip those:

Step 2: Tables – Copy and Paste or Import

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:

Step 3: Create Fields in Existing Tables

If you already have existing tables for Customers, Vendors, Invoices, 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. You can copy/paste the fields from the fmAccounting Link (QuickBooks Online 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_QuickBooksID: each table that you download data into or upload data from will require this field. This field stores the QuickBooks Online 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 QuickBooks Online. You can read more about the QuickBooks ID field here.

LastAPIResult – this stores the last API request result for the current record (e.g. in Customers, Vendors, Products etc). It doesn’t need to be displayed on a user visible layout but it helpful to see the response from QuickBooks Online 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 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. You can also skip table occurrences/relationships for modules that you are not integrating with QuickBooks Online - for example if your solution doesn't include Purchase Orders then you can skip all references to the Purchase Orders tables, relationships, scripts etc.

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 at a later step. As we have not imported any scripts yet copy/pasting layout objects would mean any buttons that reference scripts will be broken.

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 to either copy/paste or import the scripts from the fmAccounting Link file. You should import all scripts in the following folders if you are intending to download/upload data from these API endpoints:

• Company
• Accounts
• Customers
• Products
• Invoices
• Estimates
• Vendors
• Bills
• Purchase Orders
• Payments

Step 7: Value Lists

 You can use FileMaker Pro to copy/paste the Value Lists from the fmAccounting Link 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.

Step 9: OnFirstWindowOpen Script Trigger

The fmAccounting Link file has a OnFirstWindowOpen Script Trigger set via the File Menu>File Options:

The OnFirstWindowOpen Script script performs a number of functions that are specific to the fmAccounting Link file, but you may need to replicate some of this functionality in your existing OnFirstWindowOpen Script Trigger in your solution file (or set a OnFirstWindowOpen Script Trigger if you do not currently have one set).

Step 10: Create buttons for QuickBooks Online API Calls

You will need to create some buttons in your existing layouts to perform the same functions (where required) as equivalent buttons from the fmAccounting Link file. For example if you already had an Invoice Details layout and didn't create a new one you will need to add the required buttons to your Invoice Details layout , e.g.:

N.B.: some of the buttons have script parameters attached to the button which are referenced by the calling script (e.g. to instruct it to upload the current record or the current found set of records). If you are creating these buttons yourself make sure you include the script parameters.

You are now ready to start testing your integration. The first step is to ensure you can authenticate successfully with the QuickBooks Online API. Authentication is handled each time you perform a script that makes a request to the API, so you can start testing scripts that download data from the QuickBooks Online API endpoints to ensure they are working as expected.