Application Parameters Graph Template

One important best practice we always recommend people to use is to keep certain pieces of data externalized from the Kitewheel hub by having a process or node retrieve the externalized data, persist (i.e. - cache) the data in an internal location for a certain amount of time, refer to the internal datasource rather than retrieving it from the external resource each time, and then refreshing the cached data every once in a while. This practice of utilizing what we call 'Application Parameters' or 'appParams' is useful for several main reasons:

  • Referring to an internal datasource (cached variable) rather than an external datasource (database) is faster 
  • Graphs that use more internal resources perform faster because they do not have to spend time requesting and receiving data from external resources (i.e. - API calls, database calls) which may or may not be overloaded or down
  • It prevents your external resource from toppling over due to usage overload 
  • Graphs that cache data can be safeguarded from having to use external resources that may be unreliable or have downtime 

Typically, application parameters are used to store certain key pieces of information that can possibly change from time to time such as:

  • Credentials / authentication tokens for 3rd party service providers (email, facebook, any API, etc.) 
  • Default content codes or responses to be sent out via Twitter or other channels
  • Counts of certain activities and transactions that will be used later or compared again for exclusion logic

It is not meant for: 

  • Storing PII data or entire batches of customer records
  • Entire lists of content codes - we would recommend creating a separate table and then caching that table as a JavaScript object instead
  • Holding any data that never changes

Out of the box, Kitewheel comes with a graph template that enables the loading and refreshing of these application parameters from a database table into a public variable as a JavaScript object. This graph is very similar to the Refresh a Public Variable Graph Template with the added business logic to set the appParams public variable. 

Supported ParamTypes are:

  • string  e.g. "string"

  • number  e.g. 12.120
  • json e.g. {"a":"1a","b":2}

The application parameters will be loaded on first use and they will only be refreshed if the last refresh was more than the number of minutes specified in the appParamRefresh public variable. This is 30 minutes by default. 

Package contents

  • Graph: refreshAppParams
  • Public Variables: 
    • appParams - persistent public variable
    • publicVariableInfo

Database Setup 

  • Create a database table called appParams like this (MySQL): 
CREATE TABLE appParams (
   paramKey varchar(100) NOT NULL,         -- This field will contain a string that allows you to make a label for the value stored in this record
   paramValue text NOT NULL,      -- This field will contain the value used in the graph 
   paramType varchar(10) NOT NULL,         -- This field denotes what the data type or format of the value is
   description varchar(200) DEFAULT NULL,  -- This field provides a description of what the record of data is for
  PRIMARY KEY (paramKey)
);

For example, if I wanted to store the authentication token and client id to use an email service provider called kwEmail, I would put the following data in the appParams table: 

paramKeyparamValueparamTypedescription
authenticationTokenabcstringauthentication token to use when calling kwEmail
clientId123numberclient id to use when calling kwEmail
someJson
{ "a" : 123, "b": "hello"}
jsonSome JSON object 
  • After creating the table, create a database connection to the database containing the appParams table

Using  

Initial Setup 

  • Create a new item from the Refresh Application Parameters custom graph template - shown here on the far right in Graphs section of the Create New Item screen. You don't need to choose a name when creating from a Graph Template

  • Update the automatically created database connection to point to the correct database connection - this is called gt_DB - for global template database - you can change the name or use an existing connection if required. The database connection is only used in the getAppParams sub-graph 
  • Create the appParams table in your database using the code sample above 
  • Create one application parameter called appParam_ExpiryMinutes in the database table to set the frequency at which the application parameters will be refreshed 
  • Create your other application parameters setting the name (must be unique), value, type and description 

Usage

  • Wherever you need up to date application parameter values add the appParamRefresh graph to your project - this is not expensive as it will only call the database if needed
  • Within a JavaScript node any application parameter can be accessed by name. Continuing with the above examples to get the authentication token, you can get the value by calling appParams['authenticationToken'] within a JavaScript that has been passed the appParams

Inside the Template

The template graph for refreshAppParams is shown below. Comments have been added to make it understandable if you wish to inspect or borrow from the graph. 

  • First check if we have ever run before - if the public variable appParams is set to the default value 'notSetYet' then we go straight to getAppParams to get the values from the database as this is the first time this has been run
  • If appParams is set then check the appParams_ExpiryMinutes value in the appParams public variable and decide if a refresh is required - if it is call getAppParams and update the next refersh time otherwise return without calling the database

Privacy Policy
© 2022 CSG International, Inc.