fmEcommerce Link (Shopify Edition) Getting Started Guide

Integration in your own FileMaker Solution

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

Addresses: this stores the Customer Address records

CollectionMetafields: this stores the Custom Collection metafield 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.

Collections: this stores the Collection (Custom and Smart) records

Collects: this stores the Collect records (links a Product to a Collection)

Customers: this stores the Customer records

CustomerSavedSearches: this stores the Customer Saved Search records

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 Shopify API keys/website values.

InventoryItems: this stores the Inventory Items records

InventoryLevels: this stores the Inventory Levels records

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

Locations: this stores the Location records

OrderDiscountCodes: this stores the Order Discount Code records (linked to parent Order record)

OrderFulfillmentItems: this stores the Order Fulfillment Item records (linked to parent Order Fulfillment record)

OrderFulfillments: this stores the Order Fulfillment records (linked to parent Order record)

OrderItemProperties: this stores the Order Item Property records (linked to parent Order record)

OrderItems: this stores the Order Item records (linked to parent Order record)

OrderItemTaxes: this stores the Order Item Tax records (linked to parent Order record)

OrderNoteAttributes: this stores the Order Note Attribute records (linked to parent Order record)

OrderRefundLines: this stores the Order Refund Line records (linked to parent OrderRefund record)

OrderRefunds: this stores the Order Refund records (linked to parent Order record)

OrderShippingLineTaxes: this stores the Order Shipping Line Tax records

OrderShippingLines: this stores the Order Shipping 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

OrderTransactions: this stores the Order Transaction records

Plugins (not required for v1.3 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.

PriceRules: this stores the Price Rule records

PriceRulesIDs: this stores the Price Rules ID records

ProductImages: this stores the Product Image records (linked to parent Product record)

ProductMetafields: this stores the Product Metafield records (linked to parent Product record)

ProductOptions: this stores the Produc tOption records (linked to parent Product record)

ProductOptionValues: this stores the Product Option Value records (linked to parent Product Option record)

Products: this stores the Product records

ProductVariants: this stores the Product Variant records (linked to parent Product record)

Provinces: this stores the Province records

Rules: this stores the Rule records

ShippingCountries: this stores the Shipping Country 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 Shopify)

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 (Shopify 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_ShopifyID: each table that you download data into or upload data from will require one of these fields. These fields store the Shopify 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 Shopify

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 Shopify API when troubleshooting API requests

Shopify(xxxxx)JSON – this calculates the necessary JSON data structure to upload/push a FileMaker record to Shopify. 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 Shopify fields to the matching FileMaker fields in Customers, Products  etc. Any table that pushes data from FileMaker to Shopify will require one of these fields, e.g.:

ShopifyCustomerJSON

ShopifyProductJSON

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:

• Shopify Settings
• Customers
• Products
• PriceRules
• Orders
• ShippingCountries
• Locations
• Collections

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

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: 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 Shopify API Calls

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

Get Shopify Settings (found on the fmEcommerce Link Preferences layout)

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 Shipping Countries (found on the fmEcommerce Link Preferences layout)

Import Locations (found on the fmEcommerce Link Preferences layout)

Import Price Rules (found on the fmEcommerce Link Preferences layout)

Import Custom Collections (found on the fmEcommerce Link Preferences layout)

Import Smart Collections (found on the fmEcommerce Link Preferences layout)

Import Customer Saved Searches (found on the fmEcommerce Link Preferences layout)

Import Inventory Levels (found on the Locations Form layout)

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

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

Customers: Update from Shopify (found on the Customers Form layout)

Price Rules: Push to Shopify – Current Record (found on the PriceRules Form layout)

Price Rules: Push to Shopify – Found Set (found on the PriceRules Form layout)

Price Rules: Update from Shopify (found on the PriceRules Form layout)

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

Products: Push to Shopify – Current Record (found on the Products Form layout)

Products: Push to Shopify – Found Set (found on the Products Form layout)

Products: Update from Shopify (found on the Products Form layout)

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

Products: Download Product Metafields (found on the Products Form layout)

Inventory Items: Push to Shopify – Current Record (found on the InventoryItems Form layout)

Inventory Items: Push to Shopify – Found Set (found on the InventoryItems Form layout)

Inventory Items: Update from Shopify (found on the InventoryItems Form layout)

Inventory Levels: Set Inventory Level in Shopify (found on the InventoryLevels Form layout)

Inventory Levels: Adjust Inventory Level for Location (found on the InventoryLevels Form layout)

Inventory Levels: Delete Inventory Level in Shopify (found on the InventoryLevels Form layout)

Custom Collections: Push to Shopify – Current Record (found on the Collections Form Custom layout)

Custom Collections: Push to Shopify – Found Set (found on the Collections Form Custom layout)

Custom Collections: Update from Shopify (found on the Collections Form Custom layout)

Custom Collections: Download Custom Collection Image (found on the Collections Form Custom layout)

Custom Collections: Download Collection Products (found on the Collections Form Custom layout)

Smart Collections: Push to Shopify – Current Record (found on the Collections Form Smart layout)

Smart Collections: Push to Shopify – Found Set (found on the Collections Form Smart layout)

Smart Collections: Update from Shopify (found on the Collections Form Smart layout)

Smart Collections: Download Custom Collection Image (found on the Collections Form Smart layout)

Smart Collections: Download Collection Products (found on the Collections Form Smart layout)

Smart Collections: Update Product Sort Order (found on the Collections Form Smart 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 Shopify 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 Shopify API endpoints to ensure they are working as expected:

1. Shopify Settings
2. Shipping Countries
3. Locations
4. Products
5. Price Rules
6. Customers
7. Collections
8. Saved Customer Searches

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