Storefront Emulator

When you are developing a plug-in for the interworks.cloud platform you will soon find the need to test your implementation. You can make this happen easily by using the Storefront Emulator. The Emulator is a lightweight mocked Storefront that enables you to load your code and debug it just like it was loaded in the Storefront but with the perks that come with a mocked environment, such as ease of deployment, short load times (no DB is needed, no activation, etc) and more.

Step-by-step guide

Download  the Emulator

The Emulator is simply a web app solution with some example projects included. Download the solution, extract it and open it with Visual Studio.

Projects structure

The Solution already contains some example projects. Depending on the type of the plugin and its needs, the projects you need to build vary.

Configuring the Emulator

Out-of-the-box the Emulator comes with some basic data to get you started. These data are persisted in the file named "Storage.json". If you delete this file it will be recreated with these basic data. You can edit the storage file to configure the emulator to your needs.

 "Storage.json" example data
Storage.json
{
  "application": {
    "path": "https://localhost:44331/"
  },
  "paymentGateways": [
    {
      "id": "1",
      "name": "Foo Redirect",
      "type": "foo-redirect",
      "settings": {
        "LiveMode": false,
        "IsActive": true
      }
    }
  ],
  "paymentMethods": [
    {
      "id": "8726A22B-878B-4100-8CB0-51327FA74363",
      "name": "Foo Redirect",
      "gatewayId": "1"
    }
  ],
  "organization": {
    "name": "Emulator Organization"
  },
  "account": {
    "id": 1,
    "name": "Emulator Account",
    "companyName": "Emulator Company",
    "email": "account@emulator.com",
    "phone": "1234567890",
    "paymentMethodId": "8726A22B-878B-4100-8CB0-51327FA74363",
    "currencyId": "1CF82613-4DEC-4AA4-B4C7-BB172CF2699C",
    "contact": {
      "email": "contact@emulator.com"
    }
  },
  "storefront": {
    "paymentMethodId": "81561DD5-79D9-435F-92E6-CEBD19594D2A"
  },
  "currencies": [
    {
      "id": "1CF82613-4DEC-4AA4-B4C7-BB172CF2699C",
      "name": "US Dollar",
      "sign": "$",
      "code": "840",
      "mnemonic": "USD",
      "decimals": 2,
      "decimalSeparator": ".",
      "groupSeparator": ",",
      "positivePattern": "$ n",
      "negativePattern": "-$ n"
    },
    {
      "id": "25CF77B5-5B6C-4F83-B7F6-CC18B241E45C",
      "name": "Euro",
      "sign": "€",
      "code": "978",
      "mnemonic": "EUR",
      "decimals": 2,
      "decimalSeparator": ",",
      "groupSeparator": ".",
      "positivePattern": "$ n",
      "negativePattern": "-$ n"
    }
  ],
  ......
}

The Storage tries to mimic the real DB structure to emulate a live environment as close as possible. So you need to make your self familiar with some concepts of the Platform.

Application

Setting the correct path is mandatory. Otherwise, you will end-up will 404 errors or redirecting the User to incorrect URLs.

Account

This would be the user's account used throughout the Emulator. You can set here which Currency the account uses to make any payments and which Payment Method of the ones setup. You may setup multiple Payment Methods and easily change the selected one by just editing the Account's config.

Payment Gateways

The "adapter" between our Platform and third-party systems to communicate with and charge a Credit Card. Here you should add your own with any settings needed for the API to function properly.

Payment Methods

A Payment Method is how the Account will pay for goods. In a real environment, a Payment Method can be Cash, Bank Deposit or some Payment Gateway. For the Emulator only the Payment Gateway option is available since the others are not really useful for any development cases. You should add a new Payment Method associating it with the Payment Gateway you wish to develop for and give it a descriptive name. Otherwise, you can keep an existing Payment Method and just change its associated Payment Gateway.

Organization

The "umbrella" under all Accounts live.

Currency

A Currency should be configured according to ISO4217 standards because it is used by the Payment Gateways and should adhere to the correct codes and mnemonics of a real currency. You can add as many as you want but only the one set in the Account will be used in the transactions.

Storefront

For reasons that are beyond the scope of this article you should set the Storefront paymentMethodId to point to the Payment Method you wish to test. 

Strings

A collection of text/strings that are used for internationalization (i18n). If you are going to make use of our Platform i18n you should place here any strings you need.

Payment Profiles

A Payment Profile is an abstract idea of a saved Credit Card or Bank Account or whatever that is saved and used for recurring charges. As you play with the Emulator, any saved profiles will appear under this node. You can delete the list if it's getting large.

Payments

A Payment is considered a transaction that is initiated for a specific amount and currency in order to charge a Credit Card or Bank Account or any other mean. Any initiated payments and their status will appear under this node. You can use this list to debug your implementation. You can delete the list if it's getting large.

Testing your code

Hit "Run - F5" in Visual Studio →  ( Chrome will open... ) -> Select the module you are developing a plugin for.