fmEcommerce Link (Shopify Edition) v2 Getting Started Guide

Shopify Setup

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

1. generate the credentials for a private/custom Shopify app integration in the Shopify store admin
2. copy/paste the keys into the fmEcommerce Link (Shopify Edition) Setup screen

N.B. In January 2022 Shopify announced that Private apps were now deprecated and that going forward you will now need to use Custom apps and authenticate with access tokens instead of using the API Key/Password and basic HTTP authentication that Private apps used.

From February 2022 you can no longer add a new Private app to your Shopify store - existing Private apps can still be used and modified. If you have already created a Private app you can copy/paste the Private app keys and use these with versions of fmEcommerce Link earlier that 2.1. Otherwise you can use v2.1 or later of fmEcommerce Link with a Custom app and copy the access code.

Private apps: you can follow the instructions on the Shopify site for generating the private application API keys – this should only take a few minutes. We have a short video demonstrating the setup of the Private app API keys – check out the videos page to view this video.

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

Website: enter the URL to your Shopify store

API Key: enter the API Key you generated when creating the Shopify private application

API Password: enter the API Password you generated when creating the Shopify private application

Custom apps: you can you can follow the instructions on the Shopify site for installing a Custom app for your store and generating the Admin API Access Token – this should only take a few minutes. We have a short video demonstrating the setup Custom apps and access tokens – check out the videos page to view this video.

Once you’ve created your access token you open the fmEcommerce Link (Shopify Edition) file and click the SETUP navigation button at the top of the screen which takes you to the Shopify Preferences screen where you can enter the URL to your Shopify store and also the Admin API access token that you have generated.

Once you have completed the Private app or Custom app setup you are now ready to test that you can authenticate and communicate with the Shopify API running on your store. A quick way to test this is to download some configuration data from your Shopify store. Click on the Get Shopify Settings button. If it is successful it will download all your Store settings from Shopify into the fmEcommerce Link (Shopify Edition) file:

If there was an error downloading data or communicating with the Shopify 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 Shopify you can download the remaining setup data, including:

• Products
• Price Rules
• Customers
• Orders
• Locations
• Inventory Levels
• Shipping Countries
• Collections (Custom and Smart)
• Customer Saved Searches

Once you have been able to successfully download Products etc you could then try creating a Customer in the fmEcommerce Link (Shopify Edition) solution file and pushing that to the Shopify API. If successful you can then login to your Shopify 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 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

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)

Webhooks: this stores the Webhooks records

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

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

Step 7: Value Lists

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

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 All Webhooks (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: Update Inventory Level from Shopify (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)

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

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

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

Webhooks: Delete Webhooks in Shopify (found on the Webhooks 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.

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