fmEcommerce Link (WooCommerce Edition) Getting Started Guide

We recommend the following WooCommerce API reference sites for details on how to enable the REST API and documentation around each of the API endpoints:

WooCommerce REST API

WooCommerce REST API Technical Documentation

WooCommerce Setup

Setting up your WooCommerce site to allow access from the fmEcommerce Link (WooCommerce Edition) file only takes a few minutes – you need to complete the following steps:

1. enable the WooCommerce REST API
2. ensure WordPress Permalinks are turned on
3. generate the WooCommerce API Keys
4. copy/paste the keys into the fmEcommerce Link (WooCommerce Edition) Setup screen

You can follow the instructions on the WooCommerce site for enabling the REST API, turning on Wordpress Permalinks and generating the API keys – this should only take a few minutes. We have a short video demonstrating the setup of the WooCommerce API keys – check out the videos page to view this video.

Once you’ve created your API keys you open the fmEcommerce Link (WooCommerce Edition) file and click the  SETUP  navigation button at the top of the screen which takes you to the WooCommerce Preferences screen where you can enter the HTTPS URL to your WooCommerce website and also the keys that you have generated

Website: enter the HTTPS URL to your WooCommerce website

Consumer Key: enter the Consumer Key you generated on your WooCommerce API Setup

Consumer Secret: enter the Consumer Secret you generated on your WooCommerce API Setup

You are now ready to test that you can authenticate and communicate with the WooCommerce API running on your website. A quick way to test this is to download some configuration data from your WooCommerce site such as Tax Rates and Tax Classes. Click on the Tax Rates TAB and then click the  Import All Tax Rates button. If it is successful it will download any Tax Rates records from WooCommerce into the fmEcommerce Link (WooCommerce Edition) file:

If there was an error downloading data or communicating with the WooCommerce API you will get an error message with some details and you can then consult the Last API Call Result field for further details.

Once you are able to download data successfully from WooCommerce  you can download the remaining setup data, including:

• Store Setup: Tax Rates, Tax Classes, Payment Gateways, Shipping Methods, Shipping Zones, Shipping Zone Locations and Shipping Zone Methods
• Products Setup: Attributes, Terms, Categories, Shipping Classes and Tags
• Coupons
• Customers
• Orders
• Products
• Product Variations

Once you have been able to successfully download Tax Rates etc you could then try creating a Customer and Coupon in the fmEcommerce Link (WooCommerce Edition) solution file and pushing that to the WooCommerce API. If successful you can then login to your WooCommerce website and confirm all the FileMaker data has come across correctly.

Integration in your own FileMaker Solution

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

N.B. as we are continually updating the fmEcommerce Link file the screenshots below might not look exactly the same as what you see. Please refer to your fmEcommerce Link file for the latest version of these.

Step 1: Custom Functions – Copy and Paste or Import

This requires FileMaker Pro Advanced – you can either copy the Custom Functions from the fmEcommerce 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

This requires FileMaker Pro Advanced – you can either copy the Tables from the fmEcommerce 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:

Attributes: this stores the Product Attribute records

Categories: this stores the Product Category records

Countries: this stores the Country records – if you already have a Countries table or all your Customers and transactions are restricted to just a single Country you won’t need to import this. It’s mainly used for the Country Code value list and is not mandatory.

Coupons: this stores the Coupon records

CouponsCategories: this stores the Coupon Category records

CouponsProducts: this stores the Coupon Product records

Customers: this stores the Customer records (n.b. a Customer record is only created when a user is at the checkout stage and selects the option to create an account. They are added to the WordPress Users table)

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. Its main purpose is to store the WooCommerce API keys/website values.

Media: this stores the Media Library records for use with the WordPress API (upload media files directly from FileMaker container fields)

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

OrderItemMeta: this stores the Order Item Meta records

OrderItems: this stores the Order Item (line item) records

OrderItemTaxes: this stores the Order Item Tax records

OrderNotes: this stores the Order Note records

Orders: this stores the Order records

OrdersCouponLines: this stores the Order Coupon Line records

OrdersFeeLines: this stores the Order Fee Line records

OrdersRefundLines: this stores the Order Refund Line records

OrdersShippingLines: this stores the Order Shipping Line records

OrderTaxLines: this stores the Order Tax Line records

Plugins (not required for v1.5 or later): this stores the plug-ins required by the fmEcommerce Link file –  if you already have a table for plug-ins you won’t need to import this, or you could store the plugin fields in a single record preferences table. If you are going to copy the Plugins table make sure that you import all the records from the fmEcommerce Link file into your new Plugins table.

ProductAttributeOptions: this stores the Product Attribute Options records

ProductAttributes: this stores the Product Attribute records

ProductCategories: this stores the Product Category records

ProductDownloads: this stores the Product Download records

ProductImages: this stores the Product Image records

Products: this stores the Product records

ProductVariations: this stores the Product Variation records

ProductsCrosssells: this stores the Product Crosssell records

ProductsUpsells: this stores the Product Upsell records

ProductTags: this stores the Product Tag records

ShippingClasses: this stores the Shipping Class records

ShippingMethods: this stores the Shipping Method records

ShippingZones: this stores the Shipping Zone records

ShippingZoneLocations: this stores the Shipping Zone Location records

ShippingZoneMethods: this stores the Shipping Zone Method records

Tags: this stores the Tag records

TaxClasses: this stores the Tag Class records

TaxRates: this stores the Tax Rate records

Terms: this stores the Term records

Valuelists: this stores the Valuelist records used in many of the drop down lists/menus in the fmEcommerce Link file (designed to replicate the menu choices in WooCommerce)

Step 3: Create Fields in Existing Tables

If you already have existing tables for Customers, Orders, OrderItems, 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 fmEcommerce Link (WooCommerce 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_WooCommerceID: each table that you download data into or upload data from will require one of these fields. These fields store the WooCommerce 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 WooCommerce

LastAPIResult – this stores the last API request result for the current record (e.g. in Customers, Orders, Products etc). It doesn’t need to be displayed on a user visible layout but it helpful to see the response from WooCommerce API when troubleshooting API requests

WooCommerceXXXXJSON – this calculates the necessary JSON data structure to upload/push a FileMaker record to WooCommerce. This calculation will need to be updated to resolve any missing field references to reflect the structure of your solution file. You are essentially mapping the WooCommerce fields to the matching FileMaker fields in Customers, Coupons  etc. Any table that pushes data from FileMaker to WooCommerce will require one of these fields, e.g.:

WooCommerceCustomerJSON

WooCommerceCouponJSON

Step 4: Relationship Graph – Table Occurrences and Relationships

You will need to recreate the Table Occurrences and Relationships from the fmEcommerce 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 fmEcommerce 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 fmEcommerce 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.

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

• WooCommerce Settings
• Customers
• Products
• Coupons
• Orders
• Categories
• Tags
• Tax Rates
• Tax Classes
• Shipping Classes
• Product Attributes
• Shipping Methods
• Shipping Zones
• Payment Gateways
• Terms

You can generally not import scripts in the following folders as they are used in the fmEcommerce Link demo file and usually not required for your solution file:

System

Do import these script from this folder:

System Install Solution Plugins (not required for v1.5 or later)

Developer

N.B.: some of the scripts perform other scripts which include script parameters which are referenced by the calling script (e.g. when performing the authentication script step and passing the keys for the API authentication script). If you are creating these scripts yourself make sure you include the script parameters. We use the NightWing Enterprises method for passing multiple script parameters which requires the DeclareVariables custom function. You can change this to your preferred method for passing multiple script parameters as required.

Step 7: Value Lists

You will need to recreate the Value Lists from the fmEcommerce Link file in your solution file. FileMaker Pro/Advanced v16 does support copy/pasting of Value Lists, however previous version do not support copy/pasting or importing of Value Lists so these will need to be recreated manually if using FileMaker Pro/Advanced v12-15:

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 fmEcommerce 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 fmEcommerce 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 fmEcommerce 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). The most likely features you will need to recreate in your OnFirstWindowOpen Script Trigger include:

Ensure the BaseElements Plug-in is installed (not required for v1.5 or later): this is handled by performing the  System Install Solution Plugins script as part of the OnFirstWindowOpen Script Trigger:

N.B. if you copied the Plugins table from the fmEcommerce Link file make sure you also import the records from this table into your solution

Step 10: Create buttons for WooCommerce API Calls

You will need to create some buttons in your existing layouts to perform the following functions (where required):

Import Customers (found on the fmEcommerce Link Preferences layout)

Import Orders (found on the fmEcommerce Link Preferences layout)

Import Products (found on the fmEcommerce Link Preferences layout)

Import Tax Rates (found on the fmEcommerce Link Preferences layout)

Import Tax Classes (found on the fmEcommerce Link Preferences layout)

Import Coupons (found on the fmEcommerce Link Preferences layout)

Import Product Attributes (found on the fmEcommerce Link Preferences layout)

Import Product Attribute Terms (found on the fmEcommerce Link Preferences layout)

Import Product Categories (found on the fmEcommerce Link Preferences layout)

Import Product Shipping Classes (found on the fmEcommerce Link Preferences layout)

Import Tags (found on the fmEcommerce Link Preferences layout)

Customers: Push to WooCommerce – Current Record (found on the Customers Form layout)

Customers: Push to WooCommerce – Found Set (found on the Customers Form layout)

Customers: update from WooCommerce (found on the Customers Form layout)

Coupons: Push to WooCommerce – Current Record (found on the Coupons Form layout)

Coupons: Push to WooCommerce – Found Set (found on the Coupons Form layout)

Coupons: update from WooCommerce (found on the Coupons Form layout)

Orders: update from WooCommerce (found on the Orders Form layout)

Products: update from WooCommerce (found on the Products Form layout)

Products: download Product Images (found on the Products Form layout)

Product Variations: update from WooCommerce (found on the Products Form layout)

Product Variations: push to WooCommerce (found on the ProductVariations Form layout)

Tax Rates: download and upload Tax Rates (found on the TaxRates Form layout)

Tax Classes: download and upload Tax Classes (found on the TaxClasses Form layout)

Categories: download and upload Categories (found on the Categories Form layout)

Attributes: download and upload Product Attributes (found on the Attributes Form layout)

Terms: download and upload Attribute Terms (found on the Terms Form layout)

Shipping Classes: download and upload Product Shipping Classes (found on the Shipping Classes Form layout)

Tags: download and upload Product Tags (found on the Tags Form layout)

Payment Gateways: download and upload Payment Gateways (found on the PaymentGateways Form layout)

Shipping Methods: download and upload Shipping Methods (found on the ShippingMethods Form layout)

Shipping Zones: download and upload Shipping Zones (found on the ShippingZones Form layout)

Shipping Zone Locations: download and upload Shipping Zone Locations (found on the ShippingZones Form layout)

Shipping Zone Methods: download Shipping Zone Methods Locations (found on the ShippingZones Form layout)

You can copy/paste these buttons from the layouts in the fmEcommerce Link file.

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. We use the NightWing Enterprises method for passing multiple script parameters which requires the DeclareVariables custom function. You can change this to your preferred method for passing multiple script parameters as required.

You are now ready to start testing your integration. The first step is to ensure you can authenticate successfully with the WooCommerce 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 WooCommerce API endpoints to ensure they are working as expected:

1. Tax Rates
2. Tax Classes
3. Products Setup – Attributes, Terms, Categories, Shipping Classes and Tags
4. Coupons
5. Customers
6. Orders
7. Products
8. Product Variations
9. Tags
10. Payment Gateways
11. Shipping Methods
12. Shipping Zones
13. Shipping Zone Locations
14. Shipping Zone Methods

Once you can successfully download and upload using the scripts/buttons that you have imported you are ready to go live.