Skip to content

Settings

Jump to bottom
Ishtiaque Shahrier edited this page Oct 24, 2018 · 8 revisions

This page will describe all the settings used by the Exico Shopify Framework.

ESF (Exico Shopify Framework) uses settings in two places.

  1. Appsettings.json files
  2. Database

As for the appsettings you have two files, one is appsettings.json and the other one is development environment specific appsettings.Development.json. And they work as per the convention of the Asp Net Core framework.

Let's first look at the settings in the appsettings.json and then we will look at the settings that are found in the database.

1. Appsettings.json Files

First setting that you see is the connection string.

 "ConnectionStrings": {
    "DefaultConnection": "Server=localhost\\SQLEXPRESS;Database=ExicoShopifyFramework-DEVELOPMENT;MultipleActiveResultSets=true;Trusted_Connection=True"
  }

And it is very standard. It contains the name and connection to the MSSQL database. However the database names that is in the appsettings.json is different that the one you find in appsettings.Development.josn .

Next stop is the following section

  "ConsoleEnabled": 1,
  "AdminPassKey": "password",
  "AdminPassVal": "admin",
  "WebMsgViewName": "_ExicoWebMsg",
  "DbDropRecreateInDev": 0,
  "PrintViewFileName": 0,
  "UsesEmbededSdk": 0,
Console Enabled can be either 1 or 0 enables or disables the XConsole respectively. XConsole is a command line tool that ships with Exico Shopify Framework. If you need to know more about the console and what can you do wit this then go to the XConsole wiki page.
AdminPassKey This is used implicitly to authenticate the console with your app.
AdminPassVal This is used implicitly to authenticate the console with your app.It is strongly advised that you change this value to something hard to guess as soon as possible.
WebMsgViewName This is used internally as the main view by the WebMsg plugin. To know more about this please visit the WebMsg wiki page.
DbDropRecreateInDev This setting drops the DB and recreates it every time the app is restarted. It is helpful during the development period. And this is available only in the appsettings.Development.json and works only if the app is running in development environment.
PrintViewFileName If value is set to 1 then the framework inserts razor view file path in the rendering div as a custom html tag x-viewname. This is great when you want to replace a framework default view with your own custom razor file. In those cases enabling this setting would help you to find the view name that you want to replace. More one customizing view can be found on Customizing Views wiki page.
UsesEmbededSdk Value should be 1 if you have enabled the Shopify Embedded Sdk for your app, 0 otherwise.

Then the next section is about webhooks setup. Whatever you list here will be read by the framework and during the end of a successful installation the framework will create webhooks on the store it is currently being installed from the definitions you listed .

Note that you do not HAVE TO list the app uninstalled webhook here. The framework will auto create it for you. However for any reasons if you WANT TO then you certainly can add app uninstalled webhook def. in this list as well. In that cause framework will create the app uninstalled webhook using the definition from this list.

  "WebHooks": [],

This section expects an array of this following type of data/object

{
    "Topic": "[a_topic]",
    "Callback": "https://[app_base_url]/[a_controller]/[an-action] or  [any_url_that_can_handle_the_payload]" 
}

The web hooks topics can be found inside the Shopify documentation. Here is the link.

As for the call back URL you are allowed to use any https URL that can handle the payload. You can even use request bin or any similar service during the app development period.

After that comes the app permission/scopes settings, where you list the permissions that your app would need to work properly for a merchant store. Exico Shopify Framework will read this and during the installation ask the store owner to approve these listed permissions/scopes.The framework adds read_inventory and write_inventory as default permissions/scope for your app. But you can always remove these or add more .

"Permissions": [
  "read_inventory",
  "write_inventory"  
]

The full list of permissions (or scopes according to Shopify documentation) can be found here.

Next is database settings seed section. Although you can always directly go to the database->SystemSettings table and set these settings yourself, the framework gives you an opportunity to seed/overwrite the SystemSettings table settings value right from the appsettings.json file. So any field name that is listed inside the SettingsSeed section will replace the corresponding field value in the SystemSettings table.

  "SettingsSeed": {
    "SECRET_KEY": "shopify-app-secret-key", 
    "API_KEY": "shopify-app-api-key", 
    "PRIVILEGED_IPS": "127.0.0.1", 
    "SEND_GRID_API_KEY": "sendgrid-api-key", 
    "APP_BASE_URL": "https://localhost:44300", 
    "APP_VERSION": "1.0.0",
    "SHOPIFY_EMAILS_FROM_ADDRESS": "an_email_address",
    "SHOPIFY_EVENT_EMAIL_SUBSCRIBERS": "email_addresses_comma_seperated",
    "APP_NAME": "My Shopify App",
    "APP_SUPPORT_EMAIL_ADDRESS": "aupport_email_address"
  }

Database and all tables are auto created when you run the app.

Description of each setting items in the above SettingsSeed section can be found later in this page in the Database Settings section.

Next we look at the Plan/Subscription data seeding setting. By default when the framework creates the database it creates two tables for plans or subscriptions management data. But it doesn't populate any of those tables. You always have the option to directly go to the database and populate plan/subscription data right in the database , or you can do it here. More about plan data and associated tables are discussed in the Plans, App features & Subscriptions wiki page.

  "PlansSeed": [
    {
      "Name": "Test",
      "TrialDays": 5,
      "IsTest": true,
      "DisplayOrder": 1,
      "Price": 0.01,
      "Description": "This is a test plan",
      "Footer": "Test footer.",
      "Active": true,
      "IsDev": false,
      "IsPopular": true,
      "PlanDefinitions": [
        {
          "OptionName": "Feature1",
          "OptionValue": "Value1",
          "Description": "Enables feature1"
        }
      ]
    }
  ]

At the time of writing this documentation no web admin UI is available to manage plans/features/subscriptions data. But you can do it from the XConsole using command line interface or directly in the database.

Next we have admin user seed data setting. This section is read during the app start up and used to create initial admin user for the app. Concept is similar to the PlansSeed section.

  "AdminSeed": {
    "UserName": "your-development-store.myshopify.com",
    "Email": "store-email",
    "MyShopifyDomain": "your-development-store.myshopify.com",
    "ShopifyAccessToken": "shopify-access-token", 
    "ShopifyChargeId": "", 
    "BillingOn": "2018-01-01",
    "PlanId": 1,
    "Discount": "" 
  }

Same as **PlansSeed ** you can always go to the database directly and enter user/admin user data in the correct tables. But you have an opportunity to do it here in the appsettings.json file.

To know more on user creation and user related information please see the User Management wiki page.

At the time of writing this documentation no web admin UI is available to manage users. But you can do it from the XConsole using command line interface.

2. Database Settings

If you connect to the database and query the SystemSettings table then you will be presented with these following settings.

To access these following database settings in your app use IDbSettingsReader as a parameter in your controller constructor and the actual default implementation will be injected into that controller.

Setting Name Description
ACCOUNT_CONTOLLER Default account controller name. This controller takes care of store login and logout. Default value is Account which is a built in controller.
APP_VERSION Version of your app.
SHOPIFY_EVENT_EMAIL_SUBSCRIBERS Email address that will receive any emails generated by the app/framework. Use comma to enter multiple email addresses.
SHOPIFY_EMAILS_FROM_ADDRESS Email address that will be used as from address for any emails that are generated by the framework/app.
SHOPIFY_APP_STOER_URL Shopify app store URL. Default is https://apps.shopify.com/
SEND_GRID_API_KEY API key for sending emails via SendGrid.
SECRET_KEY Secret key of your Shopify app. Get it from Shopify Partners Portal
APP_BASE_URL App URL without ending trail. A valid sample value can be https://localhost:4300
APP_NAME App name same as Shopify app store.
API_KEY API key of your Shopify app. Get it from Shopify Partners Portal
APP_SUPPORT_EMAIL_ADDRESS App support email address. This where all support emails will go.
WELCOME_EMAIL_TEMPLATE A welcome message template for new users.It can contain HTML. Default welcome message is Welcome to the app!
PRIVILEGED_IPS List of privileged IP addresses.Use comma for multiples. Default value is 127.0.0.1. This IPs are treated as trusted IPs. These IPs are allowed to connect via XConsole, are able to see Dev Plans during the installation process, detailed error messages are display for these IPs etc etc.
UNINSTALL_CONTROLLER Default app uninstall controller name. Default value is the built in controller called AppUninstalled
SHOPIFY_CONTROLLER Default my Shopify controller name. This is controller will handle all communications between Shopify and your app. The default value is the build in controller called Shopify
MY_PROFILE_CONTOLLER Default my profile controller name. This controller is responsible for display profile/account information of a paid customer. The default value is MyProfile while is a built in controller.
DASHBOARD_CONTOLLER Default dashboard controller name. This is the controller that displays the landing page when a paid customer tries to access the app from their store admin. The default value is Dashboard which is a built in controller.
SEEDER_FRAMEWORK_VERSION Version of the Exico Shopify Framework that created this database. Notice it is the version number not the built number.
PASSWORD_SALT Default user password salt. This is used by the DefaultPasswordGenerator to create password for subscribed users during the app installation process.

Please note that when the app starts the framework reads the SystemSettings table JUST ONCE and then it caches the values into memory. Therefor if you change any settings in the database SystemSettings table directly or via the XConsole, while the app is running, the changes won't be picked up by the app until you either restart the app or refresh the settings cache using the XConsole command.

Clone this wiki locally