Skip to content

Advanced Features

Jump to bottom
Cortex R&D Inc. edited this page Oct 12, 2024 · 17 revisions

Advanced Features

The features labeled as "advanced" necessitate preliminary configuration before activation. They are designed to establish and utilize communication channels among different components of your application, unlocking robust administrative functionalities. This suite of advanced features is tailored to optimize interaction and coordination within your app, offering a higher level of control and efficiency in management tasks.

iFrameWnd

This concealed utility sub-page encompasses multiple views, each dedicated to facilitating essential background tasks automatically. These include Heartbeat Monitoring for system health checks, User Preferences management, detailed Account Logging, as well as the management of both User and Public Filters. Additionally, it supports Remote Software Updates, ensuring the system stays current with the latest enhancements. This comprehensive suite of tools operates behind the scenes to maintain smooth and efficient system functionality.

Heartbeat Monitoring

Heartbeat Monitoring is a feature that enables your application to continuously monitor the activity status of an account. This functionality facilitates the generation of timely alerts and supports the execution of remote software updates, ensuring that your application remains responsive and up-to-date with the latest changes or requirements.

User Preferences

This feature serves as a versatile repository for various account-related details. This system comes pre-equipped with a few standard preferences, and additionally offers the flexibility to incorporate custom preferences as needed. Structured as a string in JSON format, it eliminates the necessity for separate fields for each new parameter. Simply by adding a new additional object property, it seamlessly expands to incorporate the additional information, providing a dynamic and efficient way to manage user preferences.

Account Logging

This will provide comprehensive logging capabilities to your application. All logs are connected to an account, and can collect vast amounts of information related to the following:

  • Login date/time
  • IP address
  • OS type/version
  • Browser type/version
  • APP+KTL versions
  • Navigation history, including URL, searches and filters
  • Typical log types as Critical, App Errors, Server Errors, Warnings, Debug and Information
  • Your own app-specific log types as well
  • User activity: count of mouse clicks and keypresses

WARNING!!! This feature can use a lot of API calls in some cases. It is your responsibility to perform regular/frequent checks on your API usage. You may decide to disable some types of logging events to keep them within safe limits.

This is done via the ktl.log.setCfg function for the more general flags. You can also achieve a finer level of control using the logCategoryAllowed callback to your app where more specific conditions can be applied.

Remote SW Updates

Have you ever wished for the ability to prompt all users to refresh their pages to view the latest code or updates from the Builder? Now, that capability is within reach. Whenever there's a need to initiate a remote refresh across all users, this feature provides the perfect solution. It ensures that everyone has access to the most recent changes and updates in real-time, enhancing the overall user experience.

User Filters

The User Filters feature not only allows you to create named buttons that are stored in localStorage, but also offers the capability to sync your settings with Knack. With some initial setup, you can effortlessly upload your settings to Knack and retrieve them as needed, regardless of location or device. This dual-functionality acts both as a backup mechanism and a means to transfer settings across different devices or browsers (refer to the note below).

However, be aware that migrating filters from one application to another, such as from a main application to a temporary development version, might lead to some filters becoming non-functional. This is typically due to changes in record IDs for connected fields in the new environment. This behavior is expected, and the solution is to reconfigure the settings and save them again using the same button name.

Public Filters

Individuals assigned the Public Filters role now have the added capability to not only create a User Filter but also to designate it as Public. By right-clicking on a User Filter and selecting the 'Set as Public' option, the filter is uploaded to the cloud, making it accessible to all users on that specific page and view. Furthermore, the privilege of reordering filters through drag-and-drop, renaming, or deleting them is exclusively reserved for users with the Public Filters role. This feature ensures a more streamlined and collaborative filtering experience across the user base.

Pre-requisites

Customization Principles

Before proceeding with the Setup section that follows, it is assumed that the reader is familiar with the principles of KTL Customization found in this page: https://github.com/cortexrd/Knack-Toolkit-Library/wiki/Customizing-Features#customizing-features

Also, it is assumed that your Accounts table still has its default name. If you renamed it, you would need to use the function ktl.iFrameWnd.setCfg to set the variable accountsObjName accordingly.

Naming Conventions

Important!!! Throughout the following sections, whenever we mention the name of a table, a field or a view title, it must be written exactly as shown, case sensitive, spaces, punctuation, everything. It is recommended to copy/paste such text to avoid any typos.

Defaults

IMPORTANT: For any setup parameter that is omitted from the documentation for a field or a view, it means that you shall use the default.

Creating an Invisible Menu

An initially hidden menu might appear unconventional, yet it's poised to demonstrate considerable utility. This design facilitates the inclusion of various utility pages, which, while not necessary for regular user visibility, remain accessible to developers through direct URLs. Additionally, it supports the iFrameWnd in executing numerous background operations effectively.

We will now create a hidden menu that will be your default place for any future utility hidden pages.

  1. Add a new Dropdown Menu named Invisible Menu.
  2. Do not add any page yet, click Continue at bottom.
  3. In settings, uncheck Include this page in the Page Menu.

The iFrameWnd will soon be its first resident.

Creating the iFrameWnd

For a description of what is the iFrameWnd, see this page: https://github.com/cortexrd/Knack-Toolkit-Library/wiki/Features-Overview#iframe-window

  1. Create a new Login Page accessible to all users
  2. Page Name: iFrameWnd
  3. Its URL is automatically set to iframewnd
  4. Assign it to the Invisible Menu above

This page will be the placeholder for the next features. For now, leave it blank and we’ll get back to it later.

To activate this feature, you must set the iFrameWnd flag to true in the ktl.core.setCfg function.

If not done already, take a moment to read that page: https://github.com/cortexrd/Knack-Toolkit-Library/wiki/Customizing-Features#customizing-features

This section contains what you’ll need to do the set-up: https://github.com/cortexrd/Knack-Toolkit-Library/wiki/Customizing-Features#the-ktl-setupscallbacks

Adding the Roles

Create these roles:

  • Developer
  • Bulk Edit
  • Bulk Delete
  • Bulk Copy
  • Public Filters
  • Sysop
  • SW Update (to implement)

Assign them all to yourself.

Adding the Fields

Accounts Table

See Pre-requisites above if you changed the name of the Accounts table.

  1. User Prefs: Paragraph Text
  2. SW Version: Short text.
  3. UTC HB:
    1. Date/Time
    2. Date Format: mm/dd/yyyy
    3. Default Date: none
    4. Time Format: military
    5. Default Time: none
  4. TZ:
    1. Number
    2. No decimals.
  5. LOC HB:
    1. Type: Equation
    2. Equation Type: Date
    3. Date Type: hours
    4. Result Type: Date
    5. Equation Editor: {UTC HB}+{TZ}
    6. Date Format: mm/dd/yyyy
    7. Time Format: military.
  6. Online:
    1. Type: Yes/No
    2. Default No
    3. Input: Checkbox
  7. UTC ACT: Type: Date/Time, Date Format: mm/dd/yyyy, Time Format: military.
  8. LOC ACT:
    1. Type: Equation
    2. Equation Type: Date
    3. Date Type: hours
    4. Result Type: Date
    5. Equation Editor: {UTC ACT}+{TZ}
    6. Date Format: mm/dd/yyyy
    7. Time Format: military.

App Settings Table

Create a table named App Settings with these fields:

  1. Item:
    1. Rename the default first field from App Settings Name to Item
    2. Set it as the table’s Display Field
    3. Sort: Item, a to z
  2. Value: Paragraph Text
  3. Date/Time:
    1. Type: Date/Time
    2. Date Format: mm/dd/yyyy
    3. Time Format: military

User Filters Table

Create a table named User Filters with these fields:

  1. Account: Connection to Accounts, all settings at default
  2. Date/Time:
    1. Type: Date/Time
    2. Date Format: mm/dd/yyyy
    3. Default Date: Current Date
    4. Time Format: military
    5. Default Time: Current Time
  3. Filters Code: Paragraph Text
  4. Table’s settings:
    1. Display Field: Account
    2. Sort: Account, a to z

Delete the first default field created: User Filters Name.

Account Logs

  1. Create a table named Account Logs and add these fields:
    1. Log Nb: Type: Auto-Increment.
    2. Account: Type: Connection to Accounts, all settings at default.
    3. Date/Time: Type: Date/Time, Date Format: mm/dd/yyyy, Default Date: Current Date, Time Format: military, Default Time: Current Time.
    4. Log Type: Type: Short Text.
    5. Details: Type: Paragraph Text.
    6. Log Id: Type: Short Text. See note below for details.
    7. Email To: Type: Email.
    8. Table’s settings: Display Field: Account, Sort Order: Log Nb, low to high.

Adding the Views

iFrameWnd Page

  1. Add a Form view:
    1. Updates the currently logged-in account
    2. Title: Heartbeat
    3. Submit rules: auto-reload
    4. Confirmation message: Heartbeat sent successfully
    5. Fields on first line:
      1. SW Version
      2. UTC HB
      3. LOC HB, as read-only
    6. Fields on second line:
      1. Online
      2. UTC ACT
      3. TZ
  2. On a second row, add a Details view:
    1. For Logged-in Account
    2. Fields: User Prefs
    3. Title: Current User Prefs _ar=60
  3. Still on second row, at right, add a Form view:
    1. Updates the currently logged-in account
    2. Fields: User Prefs
    3. Title: Update User Prefs
    4. Submit rule: auto-reload
  4. On a third row, add a Grid view:
    1. Displays App Settings
    2. Title: App Settings _ar=60
    3. No Search
    4. Inline editing: On
    5. 10 records at a time
    6. No filtering
    7. Add all fields
    8. Set Value’s Shorten Text to 75 characters
    9. Source filter: Item starts with APP
  5. On fourth row, add a Grid view:
    1. Displays User Filters connected to the logged-in account
    2. Title: User Filters _ar=60
    3. Remove the Account column and leave only Date/Time and Filters Code
    4. Set Filters Code’s Truncate Text to 75 characters
    5. Limit number of records to 1
    6. No search
    7. Inline Editing: On
    8. 10 records at a time
    9. No filtering
  6. On fifth row, add a grid view that display Account Logs for the currently logged-in account. @@@
    1. Once the view is added, remove all fields, then add Date/Time, Log Type, Details, Log ID, Email To and an Custom Email action with these settings, as from the screen capture KTL Account Logs Email Settings.jpg.
    2. The blank value to Email To in Action #2 is intended. This field also acts as a flag and resetting it to blank prevents sending the email more than once.
    3. The Outcome phrase “Account Logs - Email sent successfully” is used in the code to confirm completion, so it must be exactly the same.
    4. Set the view title to Account Logs _ar=60, disable search, enable Inline editing, 10 records at a time, no filter.
  7. Sort by Log Nb: high to low, limit to 5 records.

User Preferences Page

  1. Go to User Pages (at the bottom of the Pages view) and edit the Account Settings page
  2. Add a menu:
    1. Title: My Settings
    2. Move it to the top of the page
  3. Add a link to a new page:
    1. Title My Preferences
    2. Enter it to edit that page
  4. Add a Form view:
    1. That updates the currently logged-in account
    2. Title: My Preferences
    3. Field: User Prefs
    4. Submit rule: auto-reload

Sysop Dashboards

This section will guide you through the creation of a Sysop Dashboards menu with pages that will allow viewing and managing various system-wide information.

These will be created:

  1. A page to view all account status like heartbeats, online, latest user activity, SW Version and User Preferences
  2. A page to broadcast synchronous software updates
  3. A page to browse through all Account Logs

Sysop Dashboards menu

  1. Add a new Dropdown Menu
  2. Leave empty for now, just click the Continue button at the bottom
  3. Menu name: Sysop Dashboards

Status Monitoring

  1. Create a new Login page accessible to Sysop role
  2. Title: Status Monitoring _ar=60 _ts
  3. Icon: eye
  4. Add a Grid view that displays all Accounts
  5. Enable Inline Editing
  6. Add the narrow margins and high-density classes in the description: _cls=[ktlNarrowMarginsPage], [ktlTarget,scene] _cls=[ktlDenseGrid],[ktlTarget, $('.kn-table')]
  7. Source filter: User Status is active
  8. Fields:
    1. Name
    2. Online
    3. LOC HB
    4. UTC HB
    5. UTC ACT
    6. LOC ACT
    7. SW Version
    8. User Prefs
  9. Assign the page to the Sysop Dashboards menu

This view will refresh itself every minute, so you can assess the presence, latest activity and SW Version for each account.

Note about the Online status flag:
This flag is set to Yes programmatically by the KTL, but obviously, the only way to reset it to No would be to use some kind of supervision mechanism that declares the account being offline after a specific amount of time since the last heartbeat has been received.

This being said, you have 3 options:

  1. Ignore the Online status if it’s not important to your organization
  2. You can create some (1, 2 or 3+) daily task(s) to reset it
  3. Leave the Status Monitoring page running 24/7 on a dedicated device, so the KTL code will take care of this in real-time using API calls. This is the best option and Cortex R&D can provide such solutions using low-cost Linux devices in Kiosk mode to do it. Please enquire for more information.

SW Update

There are various reasons why you might want to broadcast a manual software update:

  • You have some new code to release
  • You want to update the KTL to a newer version
  • You want the users to fetch the latest Builder’s changes
  • Any combination of the above
  1. Create a new Login page accessible to SW Update role only. Ideally, only one person should have that role to prevent clashing updates. Otherwise, it will be crucial to establish a very clear procedure and communication protocol between the involved parties.
  2. Title: SW Update
  3. Icon: bullhorn
  4. Add a Grid view that displays the App Settings table
  5. Title: SW Update
  6. Settings:
    1. No search
    2. Inline Edit: On
    3. 10 records
    4. No filtering
    5. Source filter: Item is APP_KTL_VERSIONS
  7. Fields:
    1. Item
    2. Value
    3. Date/Time
    4. Add an Action column
      1. Header: Broadcast SW Update
      2. Link Text: BROADCAST NOW
      3. Action: Update this record, Item to a field value: Item (just a dummy action)
      4. Confirmation msg: SW Update in progress...
      5. Text style: bold red with the display rule: when Item is not blank
  8. Assign the page to the Sysop Dashboards menu
  9. Click on the BROADCAST NOW action. This will set the version number for the first time.
  10. Validate that this worked by reading the value in the grid. It should match the numbers in the Version Info Bar at top-right of the page.

Account Logging

Creating the Accounts Logs Page

  1. Create a new Login page accessible to Sysop role
  2. Add a Grid view that displays the Account Logs table
    1. Title: Account Logs _ar=60
    2. Settings:
      1. Display Field: Account
      2. Sort Order: Log Nb, low to high
    3. Fields:
      1. Log Nb: Type: Auto-Increment
      2. Account: Type: Connection to Accounts
      3. Date/Time:
        1. Date Format: mm/dd/yyyy
        2. Default Date: Current Date
        3. Time Format: military
        4. Default Time: Current Time
      4. Log Type: Type: Short Text
      5. Details: Type: Paragraph Text
      6. Log Id: Type: Short Text (see note below for details)
      7. Email To: Type: Email
  3. Assign the page to the Sysop Dashboards menu

In the iFrameWnd

  1. Add a Grid view that displays the Account Logs connected to the logged-in Account
  2. Title: Account Logs _ar=60
  3. Settings:
    1. No search
    2. Inline editing: On
    3. 10 records at a time
    4. No filtering
    5. Sort by Log Nb: high to low
    6. Limit to 5 records
  4. Fields:
    1. Date/Time
    2. Log Type
    3. Details
    4. Log ID
    5. Email To
    6. A Custom Email action with these settings: KTL Account Logs Email Settings.jpg.
    7. The blank value to Email To in Action #2 is intended. This field also acts as a flag and resetting it to blank prevents sending the email more than once.
    8. The Outcome phrase “Account Logs - Email sent successfully” is used in the code to confirm completion, so it must be exactly the same.

Note about the Log Id field

This is a unique ID that is a UTC millisecond timestamp. It is generated by the code at the moment the log is created and stored in localStorage. Its purpose is to validate that the log has been sent and received properly. With that confirmation, the log can safely be deleted from localStorage.

Testing the Features

Refresh your app to see all changes take effect.

User Preferences

  1. Click on Account Settings link at the top right of your page.
  2. Click My Preferences menu button.
  3. You will see 4 new checkboxes (dynamically generated by code):
    1. Show View ID
    2. Show iFrameWnd
    3. Show DebugWnd
    4. Show Extra Debug
  4. Check all 4 and Submit:
    1. View IDs will be shown in red next to each view
    2. The iFrameWnd will appear at the bottom of the app
    3. The DebugWnd will show up
    4. In the console output, some new logs about WndMsg processing (REQ, ACK, etc.) will be shown.
  5. Uncheck all checkboxes and Submit to hide all views and stop extra logs.

Heartbeat Monitoring

  1. Check the Show iFrameWnd checkbox from the above procedure and Submit to see the iFrameWnd again.
  2. In the iFrameWnd you will see the heartbeat being submitted every minute. All fields will be populated properly with SW versions, timestamps, time zone and the Online flag being set to Yes.

User Filters

  1. Open your app on two different devices (or browsers - ex: Chrome and Edge)
  2. Log-in with your own account in both
  3. On both browsers go to the same page, where there’s a Grid with filtering enabled
  4. In a given view, create a couple of filters in the first browser
  5. Wait about 60 seconds and in the second browser, you will see those filters appear for that same view.

Broadcasting the SW Update

Whenever you need to do a SW Update, do the following procedure:

  1. Be sure to close all browsers that you have opened on this app
  2. Open the SW Update page created previously
  3. Go back in the Builder’s Javascript pane and increment your App's version number in the global variable:
    window.APP_VERSION = '1.0.0';
  4. Copy/paste your code in the Javascript pane – but don’t save yet!
  5. Update the KTL version in the Loader if needed.
    NOTE: Sometimes you may want to intentionally hold back a KTL update until you also have an App update to push, so you can do both at the same time
  6. Save the Javascript code. Important: wait until the spinner is gone
  7. Refresh your app to get the latest version
  8. Do a quick visual check to validate the numbers in the Version Info Bar at top right
  9. Click the BROADCAST NOW action link
  10. Validate that the version in the Grid matches that of the Version Info Bar
  11. Open the Status Monitoring page to see all users’ version slowly being updated and the process completes abroad for those who are online.

IMPORTANT!!! The steps 6 to 9 must be done without interruption, otherwise all users will see their app page(s) reloading over and over again.

If this happens, click BROADCAST NOW once again and check if the value in the Grid matches the one in the Version Info Bar – as it should.

If the looping persists

If, despite the retry mentioned above, the app keeps reloading in a loop, disable the iFrameWnd flag (false) in the ktl.core.setCfg function and save your Javascript code. Once the dust has settled, you can start investigating the root cause. Usually it’s due to a typo in a field name or a view title somewhere. Check the console logs also.

Behind the scenes, this is what happens: The KTL uses an API call to update the App Settings' APP_KTL_VERSIONS record. All users with opened browsers will have their iFrameWnd detect the version change and force a page reload to get the latest code.

Those who are not online will simply get the latest code when they launch the app next time.

Public Filters

  1. Open two browsers of different types, ex: Chrome and Edge.
  2. Log-in with your account having Public Filters role, in the first browser
  3. Log-in with another account not having Public Filters role, in the second browser
  4. Go to the same page on both browsers
  5. Create two User Filters with your account
  6. Set them to Public
  7. You can drag’n drop them left and right and can rename them
  8. On the second browser, those two filters will appear about 60 seconds later
  9. The other user can’t move them, rename them nor delete them
  10. In your page, click on the padlock icon to unlock Public Filters. See notes below about the padlock icon
  11. Make changes to the filter and re-order them
  12. All changes will be reflected in the other browser about 60 seconds later

About the padlock icon

The padlock only applies to Public Filters and is only visible to users having that role.

  • Locked: Makes the Public Filters “read-only”. When you make changes to Public Filters, they won’t be saved locally or uploaded. This is useful for normal day to day usage. Otherwise, when you just want to change the sorting, searching, etc., an upload would occur each time, disturbing the others working with that view.
  • Unlocked: Makes the Public Filters “writable”. When you make changes to Public Filters, they will both be saved locally and uploaded. This is useful during (or after) an editing session, when you’re ready to broadcast the updated filters to all users. Typically, you unlock, edit all filters and lock back.

Using multiple browsers

It’s important to understand that the localStorage (where the filters information is stored) is not shared across different browser families – ex: Chrome and Edge. Furthermore, this is also true within the same browser family, when opening their private/incognito counterpart.

This means that without the automatic upload/download of filters, all users would have to re-create them when switching devices or browsers. But now, this takes care of the transfer in all cases.

This particularity can be leveraged by allowing you to log-in to 4 different accounts and/or roles at the same time. This can be very useful during testing phases for example.

Conclusion

Hope you’ll enjoy the KTL’s Advanced Features. Give us some feedback, we always love to hear from you.

Normand Defayette

Cortex R&D Inc.

Clone this wiki locally