Install Desktop Widgets

Introduction

Ombea will provide you with an MSI file that you can use for system-wide installation. If you have not received this, please contact your Ombea Account Manager.

The Desktop Widget application is installed per user, not per machine. During installation, it will be automatically registered for automatic startup every time the user logs in to Windows.

Before you start, you will need to know your WEBSITE_ID and WIDGET_ID. The instructions below start with showing you where to find them.

Get your WEBSITE_ID and WIDGET_ID

Click on Touchpoints from the left-hand menu.
Navigate through your folder structure until you find your Desktop Widget touchpoint. We will have already created this for you.
Select the Desktop Widget touchpoint and click Edit.
On the Installation pane, under the heading 'Add this snippet to your website', you will see some Javascript code.
Your Website_ID is shown in the call to the init function. For example, if you see window.oiwidgets.init("123456",u) then your WEBSITE_ID is 123456.
Copy and paste this WEBSITE_ID somewhere safe, or make a note of it.
Click Next to reach the Touchpoints pane.
Under the heading 'Online Touchpoints', you will find your Desktop Widget touchpoint. Click the pencil icon to edit this.
In the pop-up, under the heading 'Copy and paste the following JS call whenever you want the widget to show.', you will see some Javascript code.
Your WIDGET_ID is shown in the call to the show function. For example, if you see window.oiwidgets.show('654321') then your WIDGET_ID is 654321.
Copy and paste this WIDGET_ID somewhere safe, or make a note of it.

MSI Installation

The MSI file requires a number of public properties to be defined, either before or during installation.

The details for defining values for MSI file public properties in general is outside the scope of this article, however in short this could be done by either

Specifying them as arguments to msiexec during MSI installation using the following syntax (this is supported by installation administration tools such as SCCM):
msiexec /i MSI_FILE_NAME PROPERTY_A=VALUE_A PROPERTY_B=VALUE_B
Or by creating a MSI transform file (MST) and then specifying the transform file during MSI installation. This is supported by installation administration tools such as SCCM as well as installation via a GPO (Group Policy Object).

MSI Public Properties

The value of the following public MSI properties will be written into the settings.ini file which is automatically created in the application directory during installation.

WEBSITE_ID (required)
The ID of the 'Website' where the Desktop Widget is located. This is the WEBSITE_ID you made a note of earlier in this article.

WIDGET_ID (required)
The ID of the Online Touchpoint for the Widget. This is the WIDGET_ID you made a note of earlier in this article.

TIME (optional)
The earliest time of day that the widget can be shown. Further restrictions for when the widget is shown are defined in the Stream you created earlier.

Default value: 00:00

DAYS (optional)
The days of the week when the widget can be shown. Further restrictions for when the widget is shown are defined in the Stream you created earlier.

Default value:mon,tue,wed,thu,fri,sat,sun

MONTHS (optional)
The months of the year when the widget can be shown. Further restrictions for when the widget is shown are defined in the Stream you created earlier.

Default value:jan,feb,mar,apr,may,jun,jul,aug,sep,oct,nov,dec

OCCURRENCE (optional)
This property allows you to either let the widget be shown on the first, last, or all occurrences in the month of any the weekdays you specified using the DAYS property.
Possible values: first/last/all
Default value:all

For example, you may want to only show the widget on the first day of every month, or the last Tuesday of every month. If you would like to show the widget whenever the criteria are met, simply specify "all". Further restrictions for when the widget is shown are defined in the Stream you created earlier.

SETTINGS_FILE_PATH (optional)
Specifies the location of the settings.ini file. This file contains the application configuration settings. A settings.ini file will be automatically generated in the application installation directory during MSI installation. This file (./settings.ini) will be used unless a custom location of the file is specified here.

Note that in many cases you can omit this property and instead specify all application settings via the MSI public properties described above.
However in some cases you may need more flexibility in which case you can specify the location to a custom settings.ini file.

The value of this property must be either of the following:

An absolute file path, e.g. h:\ombea\desktop-widget\settings.ini
A URL, e.g. https://www.acme.com/desktop-widget/settings.ini
A relative file path (relative to the application installation directory), e.g. ..\ombea\desktop-widget\config\settings.ini.
Default value:./settings.ini

A further note on Custom settings.ini files

As mentioned above, a settings.ini file is automatically created in the application directory with its contained properties defined via the corresponding MSI public properties. One disadvantage of this approach is that, if you decide to change any of the application settings for your users, for example the time of day when the widget should be shown to the users, you will need to uninstall the application from all the end user machines and then re-install it, now with a new value for public MSI property TIME.

If you want to be able to change the application settings without having to re-install the application you can instead specify a custom location of the settings.ini file as value for the public MSI property SETTINGS_FILE_PATH.

For example you may want to put the settings.ini file on a shared network drive, or host it on a web server e.g., the web server for your corporate intranet.

Custom settings.ini file examples

Example 1

The following settings.ini file specifies that the widget may only be shown after 10:00 on Mondays, Thursdays and Fridays during
the months of August, September, October, November and December.

settings.ini

[config]

website_id=600f3e4a96e50bc7c12c4fb9

widget_id=600f3e5196e50bc7c12c4fba

time=10:00

days=mon,thu,fri

months=aug,sep,oct,nov,dec

occurrence=all

Example 2

The following settings.ini file specifies that the widget may only be shown after 15:00 on the first Monday of the month, during the months of August and September.

settings.ini

[config]

website_id=600f3e4a96e50bc7c12c4fb9

widget_id=600f3e5196e50bc7c12c4fba

time=15:00

days=mon

months=aug,sep

occurrence=first

MSI Installation Examples

In the examples below, 123456 and 654321 refer to your WEBSITE_ID and WIDGET_ID respectively.

Example 1

Installing a Desktop Widget using the default options.
Here we are only specifying the two required properties WEBSITE_ID and WIDGET_ID, and using default values for all optional public properties.

msiexec /i "Ombea Desktop Widget Setup.msi" WEBSITE_ID=123456 WIDGET_ID=654321

Example 2

Installing a Desktop Widget that only appears after a certain time of day.
Here we are specifying that the Desktop Widget should only appear to the end user at 10:00 at the earliest.

msiexec /i "Ombea Desktop Widget Setup.msi" WEBSITE_ID=123456 WIDGET_ID=654321 TIME=10:00

Example 3

Installing a Desktop Widget that only appears at certain times, on certain days, in certain months.

Here we are specifying that the widget may only be shown after 10:00 on Mondays, Thursdays and Fridays during the months August, September, October, November and December.

msiexec /i "Ombea Desktop Widget Setup.msi" WEBSITE_ID=123456 WIDGET_ID=654321 MONTHS=aug,sep,oct,nov,dec DAYS=mon,thu,fri TIME=10:00

Example 4

Installing a Desktop Widget that only appears on the first day of the month, that matches timing criteria specified in the installation.

Here we are specifying that the widget may only be shown after 15:00 on the first Monday in the month during the months of August and September.

msiexec /i "Ombea Desktop Widget Setup.msi" WEBSITE_ID=123456 WIDGET_ID=654321 MONTHS=aug,sep DAYS=mon TIME=15:00 OCCURRENCE=first

Updated on: 29/09/2022

Was this article helpful?

Thank you!