KWizCom
SharePoint Apps (add-ins) architecture
White Paper
|
Copyright
© 2005-2017 KWizCom Corporation. All rights reserved.
Company Headquarters
95
Mural Street, Suite 600
Richmond Hill, ON
L4B 3G2 Canada
E-mail: info@KWizCom.com
Web site: http://www.kwizcom.com
Sales
E-mail:
sales@KWizCom.com
Telephone: +1-905-370-0333
Contents
Contents. 3
Apps Architecture. 4
KWizCom Apps General
Architecture. 4
KWizCom CDN.. 4
KWizCom Apps Foundation. 4
How KWizCom apps are built 4
Data Flow.. 5
User Visits app settings
page to configure the app. 5
End-user VisitS the list
which was configured. 6
App Installation and
hosting requirements. 7
Installation procedure. 7
App installation. 7
KWizCom Apps Foundation
installation. 8
App version updates. 9
Apps Architecture
KWizCom Apps General Architecture
All KWizCom apps for SharePoint/SharePoint Online
are implemented the same way, utilizing KWizCom’s Apps framework. This
framework includes the following ingredients:
KWizCom CDN
The KWizCom CDN is at apps.kwizcom.com,
located on AZURE, serving all KWizCom apps for several purposes:
-
Store the actual apps code
(CSS, javascript, html content). This means that the apps are more of skeletons
or shells that download their code from the CDN. This makes the publishing and
deployment of new app versions a lot faster and easier.
-
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
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.
How KWizCom apps are built
KWizCom Apps are implemented as SharePoint-hosted
apps, coded in javascript, running in the client browser. Most of the code is
not hard-coded in the app itself, but is downloaded from
apps.kwizcom.com CDN (CSS, JS, Html content).
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.
Data Flow
This
section describes what requests are made and what data is passed during the
various usage events, after the a KWizCom app is installed.
User Visits app settings
page to configure the app
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:
-
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).
-
The client
provisions a .js file to “Site Assets” (usually a simple loader/bootstrap file)
-
The client makes a
request to the KWizCom App Foundation to configure the application. Information
sent from the app to the KWizCom Apps Foundation:
-
User context, site
URL – used by OAuth for authenticating the app. This is a part of Microsoft’s
provider hosted apps architecture.
-
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.
End-user VisitS the list
which was configured
1.
The app’s .js file
is loaded from “Site Assets” and running from the client PC.
2.
That .js file then
loads any additional artifacts from apps.kwizcom.com CDN (CSS, javascript, Html
content) that it requires to run.
3.
A request is made to
try to load the settings file for this list/product, according to the following
logic:
-
File does not exist?
Do nothing.
-
File exists?
-
The settings file is
loaded from “Site Assets” into the browser, parsed as a JSON object
-
Local JavaScript is
reading the settings object and enforces these settings on the list forms as
needed.
-
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.
App Installation and hosting requirements
Installation procedure
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.
App installation
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 installation
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.
App version updates
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).