KWizCom Apps General Architecture
KWizCom Apps Foundation
How KWizCom apps are built
User Visits app settings page to configure the app
End-user Visits the list which was configured
App Installation and hosting requirements
KWizCom Apps Foundation installation
App version updates
All KWizCom apps for SharePoint/SharePoint Online are implemented the same way, utilizing KWizCom’s Apps framework. This framework includes the following ingredients:
The KWizCom CDN is at apps.kwizcom.com, located on AZURE, serving all KWizCom apps for several purposes:
2. License service
When a user visits a list which is configured with KWizCom app, a request is made to this service to check for user license
KWizCom Apps Foundation is a vendor-hosted app that provides services to all KWizCom apps to enhance their feature set.
This app has no user interface, it is a utility app, providing services to other KWizCom apps "behind the scenes".
Why do we need it?
Instead of implementing the same capabilities in each of our apps, we gather all of these shared functions into a "utility app" that can then serve all apps. The result is smaller and faster apps, easier deployment process for our customers.
This way customers do not need to manually update their installation every time we publish changes and fixes.
All KWizCom apps interacts with KWizCom Apps Foundation and with the KWizCom license service modules.
This section describes what requests are made and what data is passed during the various usage events, after the a KWizCom app is installed.
1. Since KWizCom app is a SharePoint-hosted app, it is a sub site within your SharePoint.
2. The landing page downloads artifacts from apps.kwizcom.com CDN (CSS, JS, Html content)
3. A request is made to the KWizCom Foundation app – to make sure the Foundation is installed correctly.
Information sent by the the app: user context (for OAuth login, handled by Microsoft), and the current site URL. At this point, all KWizCom Apps Foundation does is check if it has access to that site under that user, to ensure it was configured correctly.
4. A request is made to the licensing service.
Information sent by the app: The site ID and user name are sent to check if there is a license under the site, user or domain.
* We have noted a request to avoid sending the user name in cases where a site license exists.
5. The user configures the app, the app pulls information from SharePoint using client-side object model between the user browser and the SharePoint server directly, not going through KWizCom’s servers. This is the same approach that SharePoint itself is running under, using the exact same APIs.
6. Once the user is done configuring the app and saves changes:
a. The client creates a JSON settings file and uses SharePoint API to upload it to the parent site’s “Site Assets” library (it would first try to load this file if already exists to apply changes to it rather than create a new one).
b. The client provisions a .js file to “Site Assets” (usually a simple loader/bootstrap file)
c. The client makes a request to the KWizCom App Foundation to configure the application. Information sent from the app to the KWizCom Apps Foundation:
1) User context, site URL – used by OAuth for authenticating the app. This is a part of Microsoft’s provider hosted apps architecture.
2) The product’s SKU, the list id. This information will tell KWizCom App Foundation what needs to be configured on which list. KWizCom App Foundation confirms the requesting app is installed on that site and registers the .js file that was uploaded to “Site Assets” to run on all pages needed for this list.
1. The app’s .js file is loaded from “Site Assets” and running from the client PC.
3. A request is made to try to load the settings file for this list/product, according to the following logic:
a. File does not exist? Do nothing.
b. File exists?
1) The settings file is loaded from “Site Assets” into the browser, parsed as a JSON object
3) A request to apps.kwizcom.com license service is made to check for user license. The response of this request is cached in an in-memory-cookie so it won’t be made again until the browser closes.
Note: at this stage, apart from downloading some JS/CSS files from apps.kwizcom.com, all code and logic is running on the user’s browser and uses SharePoint client-side object model to communicate directly with SharePoint.
When installing a KWizCom app, you will need to install 2 components:
1. The requested app – this is a SharePoint-Hosted app (as mentioned above), installed from the MS App Store by using Microsoft’s installer.
2. KWizCom Apps Foundation – This is a vendor-hosted app, downloaded from KWizCom’s website and manually added to your internal app catalog.
The requested KWizCom app is deployed within a site, according to the following steps:
1. Click "Add an app" while browsing the site to which you want to add the app:
2. Click the "SharePoint Store" link on the left:
You will be redirected to the Microsoft Apps Store.
3. Find the app by typing its name in the Search box (or just type "KWizCom" to find all our apps on the store)
4. Install the free version. This version includes a message that indicates that this is a free trial version.
KWizCom Apps Foundation comes in 2 access levels:
Tenant app – will allow you to add the app once for your entire tenant. This will require a tenant administrator to add and trust the app. This is recommended when you anticipate to use KWizCom apps on many site collections and don’t want to add the Foundation app to each one.
Site collection app – will allow you to add the app to a specific site collection (one or more). This will require you to be a site collection administrator on the site you are adding the app to. This is recommended when you either do not have tenant administrator permissions, or only wish to grant KWizCom components access to specific site collections.
To install KWizCom Site Collection Apps Foundation:
1a. Download this zip file, and unzip the app in your local machine.
Or to install KWizCom Tenant Apps Foundation:
1b. Download this zip file, and unzip the app in your local machine.
2. Upload the app to your app catalog. Please refer to this article about how to manage your app catalog
3. As tenant admin or Site collection admin (depending on the KWizCom foundation app type you choose in step 1), add the KWizCom App Foundation to the site collection you plan to use your KWizCom app.
KWizCom updates its apps to include new features, bug fixes, or to accommodate updates done by Microsoft to O365.
Publishing a new version of the app is done in the following way:
if the app was deployed by the Microsoft App Store, updates will come in from the store and show up in the site contents. This just updates the package, which rarely changes.
Functional updates are published to our public test environment (KWizCom fast-ring), and a week after published to production. At this point, all customers will automatically get the update version without the need for doing something.
As for KWizCom Apps Foundation: This provider-hosted add-in provides services and has no functional changes, and is published directly to production after it passed testing, so doesn’t require any re-installation by clients (automatic update).