Install/Update User Guide

 

Getting Started: Install/Update in three steps

This section will teach you how to install a new Feature and how to revert to a previous state in three easy steps. Before you start, make sure you installed the 'mockup' site following the install mockup site instructions.

Find new Feature

This section will focus on finding a feature to install. There are different ways of finding a feature. The one we are going to focus in this section is browsing a site . For more information about other ways of finding a feature, look at the Find Features section.
Before browsing a site, we will have to create a site bookmark to access it.

Create a new site bookmark

The Site should appear on the view. The provider of a feature should give you the URL of their site so you can  find their feature. We will now browse the site to discover the features.

Choose Feature

You can expand the site and the categories to see the Features. In this site you should see one category:  Red Dot Versions,  and two features:  Red Dot Feature 1.0.0 and Red Dot Feature 2.0.0.
The Preview page should now look like the following picture:
        PIC001.gif Preview Page of Red Dot 1.0.0
You may want to check the license and copyright or decide to have more information about the Feature you are about to install. 'Click' on the appropriate link at the bottom of the view to automatically open a browser that will show you the desired page.
<TIP the preference page lets you decide if you want to view the HTML page within the workbench or by launching an external browser>

Install Feature

When you are ready to install the feature click on the Install button in the Preview View. This will launch the Install Wizard.

Install Wizard

The feature will then be downloaded, verified and installed in the site. You can see the progress monitor showing you the evolution of theses tasks. During verification, you may be prompted to accept the verification. Click 'Ok' when prompted.
When the feature has been installed you will need to restart the workbench for the changes to take effect. Click 'Ok' on the dialog box.

Verify the feature has been installed

The feature you installed will add a red button icon to the tool bar when activated. To activate this specific feature customize your perspective and add the Red Dot Set Action Set:

You should now se a red button icon on the toolbar. If you click on it the following dialog box should appear, meaning the feature and associated plug-ins have been successfully installed and configured.
We will now see how to manage your feature in your configuration.

Configure Environment

A feature that is installed may be configured or unconfigured for your workspace. A configured feature means that Install/Update will 'suggests' that the runtime configures the feature to be available. An unconfigured feature means that Install/Update will make the feature unavailable to the user.
When you installed Red Dot Feature 1.0.0, Install/Update installed and configured the feature for you. You can see that in the Configuration History. For more information about Configuration History see Configuration History .
A configuration is a list of configured and unconfigured features that determine what tool you can use.
The current configuration is the configuration currently active.
For more information about configuration, see Configuring/Unconfiguring .
In this section we will add the current history configuration to the list of preserved configuration. We will unconfigure Red Dot 1.0.0, so the feature will be unavailable. Then we will restore the preserved configuration, which will re-configure the feature.

Add configuration to preserved

To add the current configuration, we will first need to find it in the list of configurations and then add it to the list of preserved configurations. The current configuration is the configuration in the configuration history folder with an icon with a running person. It is the last configuration in the list.

Rename configuration

We will rename the configuration to give it a meaningfull name.

Unconfigure Feature

We will now unconfigure the feature.

Expand Current Configuration to reveal the configured Feature.

The workspace will shut-down and restart automatically.

Restore Configuration

We shall now restore the configuration we added to preserve, so the feature will be configured again.

Verify the Feature is not available

You should not see the red button icon in the toolbar, meaning the feature was not activated

Unconfigured feature revealed
The icon Unconfigured Feature unconf_feature_obj.gif means the feature is still installed but not available at this time in your workspace. To be able to use the feature we will need to configure the feature.

Revert to preserved configuration

            We will now go back to the configuration we had previously in which Red Dot Feature 1.0.0 was configured.

The workspace will shut-down and restart automatically. After the workspace restart, the feature is configured, based on the revert configuration.
There are different way of configuring a feature. To know more about configuring and unconfiguring features see: Configuring/Unconfiguring features .

In this section you learnt how to find a feature you want to install, how to install a feature, how to unconfigure a feature and how to restore a preserved configuration. The rest of the book will go into more details.

The User Interface

This section describes in details the User Interface of the Install/Update perspective. The perspective is composed of four different views: The Configuration View to manage the configurations, the Updates View to manage update sites and features as well as searches. The Preview View is used to show the details of the element selected in the previous two views and the Web View, which is used to browse HTML document from either sites or features.

The Configuration View

The configuration view helps you manage your configurations. A configuration is a list of configured and unconfigured features that determine what tool are available fro you to use in your workspace.
Configuration View

Current Configuration

The current configuration is the configuration currently active. When you expand the Current Configuration you can see the sites you are connected to. Expanding each site reveals the list of Features you have access to. Some feature may be configured, some may be unconfigured. The configured features are the tools the Install/Update suggested the runtime to activate. To know more about configured/Unconfigured features see: Configured/Unconfigued .

Configuration History

The Configuration History folder contains the last n configurations you used. n is a number you can set in the Install/Update preference page. See: Install/Update Preference Page .
You can use the history list to see what are the different activities that occurred as well as restoring an old configuration to make it the current one.
 Install/Update creates a new configuration history when one or more activities are performed (i.e. install, configure, unconfigure etc...). When the Install/Update  creates a new configuration, it will add it to the list. If you already have n configurations, the framework will automatically delete  the oldest configuration from the list. To know when the Install/Update creates new configuration history and what are the Activities see:   Configuration History .

Preserved Configuration

The Preserved Configurations folder contains history configurations you want to keep. The framework does not automatically delete the configurations in the Preserved Configurations folder, you have to explicitly delete them.

Configured/Unconfigured

You can decide to see only the configured features or both configured/unconfigured features by clicking the 'Show Unconfigured Features' toggle button in the view tool bar. To know more about configured/unconfigured features see: Configured/Unconfigued .

Local View Toolbar Actions

Show Unconfigured Feature

This button allows you to see only the configured features or both configured and unconfigured features. Unconfigured features appear with a red circle around the icon. For more information about configuring/unconfiguring features see: Configuring/Unconfiguring .

Context Actions

This section describes the different context actions available in the Configuration View.
Go Home
This action <TODO be consistent with navigator>
Go Back
This action <TODO be consistent with navigator>
Go Into
This action <TODO be consistent with navigator>
Show Details
This action opens or refreshes the Preview View with the details of the selected element.
Properties
This opens a Dialog box that presents the label of the selected configuration. You are able to change the label of a configuration. Click Ok when you have finished and you want to preserve your changes or click Cancel if you do not want to change the properties.
Add to Preserved
 This action adds the selected configuration in the Configuration History folder to the list of preserved configuration.
Remove from Preserved
This action removes the selected configuration from the list of preserved configurations. This action will not delete any Site, Site Bookmark or Feature. This action will not delete the configuration it was created from or any other configuration.
Restore
 This action creates a new configuration based on the selected configuration and marks it as current. Install/Update will automatically configure all the features that were configured in the selected configuration you want to restore. To know more about restoring or reverting to a configuration see: Restore a Configuration/Revert to previous configuration .

The Updates View

The Updates view allows you to manage the remote sites you can install from to search for features as well as features you can install.
Updates View

My Computer

My Computer lets you browse your computer and any mounted local file to discover any site on your file system. You can also search My Computer to discover sites: see Search the file system .

Places to Visit

Places to visit are sites suggested by the features you installed for you to visit.

Available Updates

Available Updates will let you search for updates of already installed features. The search occurs in the background so you can still use the workbench while searching for updates. To know more about searching: see Search .

Sites Bookmark

A site is a location that contains features. In the Updates View, the sites contain features you can install. You can browse or search features in Site bookmarks. There are two ways of adding a site bookmark. You can use the context menu and the context action add site bookmarks, or you may browse My Computer and add a site as a site bookmark. See Context Action for more details.

Search

<TODO>

Folder

<TODO what can I store in a folder ?>

Local View Toolbar Actions

This section describes the local view toolbar actions of the Updates View.
Show Feature Categories 
When this action is selected,  you will see the features organized in categories.
Categories

When this action is not selected, you will see all the features as a list.
No Categories
Show My Computer Files 
When this action is seelcted, you will be able to browse the files when you expand MyComputer.
Browse Files

Context Actions

This section describes the different context actions available in the Updates View.
New->Site Bookmark...

Creates a new Site bookmark. This opens a Dialog box that presents the properties of the Bookmark Site you want to create. The properties of a Bookmark Site are the label you want to see in the View as well as the Address of the physical site. You have to enter the Site URL. Optionally you can enter the Site Name. If you o not enter a Site Name, it will default to the Site URL. Click Ok when you have finished and you want to preserve your changes or click Cancel if you do not want to create a new Site Bookmark.

New->Folder
This action lets you create a new Folder. When you select this action, a dialog will open.
New Folder Dialog

Type the label of the folder in the 'Name;' entry field.
Type the name of the parent folder in the 'Create in:' entry field, or select it in the 'Existing folders:' tree view. If no parent are selected, the newly created folder will appear in the updates view as a root folder.

folders folders folders
New->Search
Creates a new Search. <TODO elaborate as we may have multiples searches ? do we have extension point in the help framework so other can plugin their search doc ?>
Show Details

This action opens or refreshes the Preview View with the details of the selected element.

Refresh
This action re-initializes the content of an element <TODO see dejan>
Bookmark Location
This action lets you create bookmark site for a site found on your local file system. This opens a Dialog box that presents the properties of the selected site. The properties of a Site are the label you want to see in the View as well as the Address of the site. You are able to change the Site Name. Click Ok when you have finished and you want to preserve your changes or click Cancel if you do not want to change the properties.
Properties
This action opens a Dialog box that presents the properties of the selected site. The properties of a Site are the label you want to see in the View as well as the Address of the site. If the element you selected was a bookmark, you are able to change both the Site Name and the Site Address of the site. If you change the Site Address of a Bookmark Site you will need to 'refresh' the Bookmark Site to access its new content. Click Ok when you have finished and you want to preserve your changes or click Cancel if you do not want to change the properties.
Delete
This action removes the Bookmark Site from the workbench. This does not erase the content of the Site nor the physical remote or local Site itself.

The WebView

The Web View is <TODO >

The flat concept (see Dejan)

<TODO>

The Preview View

The preview shows information about the selected element. The preview view is different for each selected element.

You can open the preview view by either selecting an element in the updates or Configuration view, by opening a context menu on any element in the Updates or Configuration View and selecting Show Details or by open the Preview View from the Workbench menu. Select Window->Show View->Other to open the list of available Views. Expand Update Manager Folder, select Preview and Click Ok.

The 'Home' Preview view.

You can open the 'Home' Preview by clicking on the home in the local tool bar menu if the View. This view summarizes the different tasks you can achieve through the Install/Update. By using the flat concept you are able to <TODO link>
Home Preview

The current configuration Preview view

This Preview shows information about the product you are using. The content of the view depends on the product you launched.
product preview

The Site and Site Bookmark Preview View

This Preview shows the Site Address of the selected Site or Bookmark Site.
Site Preview

The Feature Preview View

This Preview View shows information about a feature.
Feature Preview  
Provider
The name of the provider of the feature.
Version
The version of the feature.
Installed Version
The list of already installed version of this feature or 'Not Installed' if no version of this feature has been configured in the current configuration.
Download Size
The maximum download size for the feature. If the site you will install the feature in already contains some of the files the feature require, the files will not be installed twice, and thus the downloaded and installed size will be smaller than the maximum one.
Supported Platforms
This expandable category shows the different supported platforms for this feature. The categories are Operating Systems, Windowing Systems, Architectures and Languages.
Description

The description of the Feature

More Info <TODO should we say it is optional ?>
Opens a page with more information about the feature. The page may be found locally or remotely.
License
Opens a page with the license of the Feature.
Copyright

Opens a page with the copyright of the Feature.

Actions

In the lower left side of the Preview View for a feature you may see one or multiple buttons. They provide you with actions you can take on the Feature depending of its configuration. If a change is pending for this feature, no actions will be available until the workbench is restarted.

The Configuration Preview View

This preview shows information about the select configuration.

Configuration Preview


Created On

The date in the current locale, the configuration was created on.

Current Configuration

If the selected configuration is the active configuration.

Activities
List of activities that led to the creation of the configuration. For more information about the differents activities, see Activities .

Configuration Reversal
In the lower left side of the Preview View for a configuration you may see one button. It provides you with actions you can take on the Configuration depending if it is the current configuration or another one. If a change is pending for a feature, no actions will be available until the workbench is restarted.

The search Preview View

<TODO depending on the search>

The Install/Update Preference Page

You can open the preference page from the Workbench main menu. Click  Window->preferences to open the Preference Dialog. Select Install/Update to reveal the Install/Update preference Page. In this page, you can modify the number of history configuration you want the workbench to manage as well as decide which browser to open .

Maximum number of 'History' configurations entry field.

Enter the number of history configurations you want the Install/Update to keep. See Configuration History for more information.

Web Links radio buttons.

When opening Web links. Allows you to choose between opening the internal WebView or opening an external browser.

Finding features

This section will explain how to find the features  to install. There are different way of looking for features; you may know exactly which feature you need and where it is located, or you may want to search for an update of an already installed feature is available, finally you may just decide to browse or search to discover new sites and new features.

Find a specific feature

This section will focus on finding a feature when you know exactly where to find it. To find a feature you may either add the Update Site that contains this feature and browse the site to find the feature or you can open the WebView and browe to the Feature WebPage.

Add a new Update Site 

To add a new Update site, open the context Menu in the Updates View and select New->Site Bookmerk....  This opens a Dialog box that presents the properties of the Bookmark Site you want to create. The properties of a Bookmark Site are the label you want to see in the View as well as the URL of the physical site. You have to enter the Site URL. Optionally you can enter the Site Name. If you do not enter a Site Name, it will default to the Site URL. Click Ok when you have finished and you want to preserve your changes or click Cancel if you do not want to create a new Site Bookmark.  

Find the feature   

Expand the site to find the feature you want. You can find the feature by looking at the label or selecting a feature and reading the preview view. To know more about preview view:  See Preview View .

Browse WebPages 

Open the WebView and enter the URL for the feature web page. Follow the indication of the webpage. <TODO web install>

Update already existing features

This section will focus on updating features that are configured in your current configuration.To know how to configure/unconfigure a fetaure; see: Configuring/Unconfiguring .<TODO only configured features ?>  

Search for updates

 To search for available updates, select Available Updates in the Updates View. In the preview view, press Search now.  This will search the site the configured feature come from for new version the installed and configured feature. During the search you will see the progress monitor move, indicating the search is in progress. When new version of configured features are found, they will appear under the progress monitor.  You can decide to see the result in a short form or an extended form by checking the 'Show results in extended form' box, under the Scope Settings section in the preview view.

Search the file system

You can decide to search the file system for updates by checking the 'Include my computer in the search' box, under the Scope Settings section in the preview view. Click on the Settings... button to customize which part of the file system you want to search.

Customize Search

You can cutomize the search for updates by creating a new search. To know how to create a new search <TODO>

Browse to discover

This section will focus on browsing update sites to find the features you want to install. All the update site appear in the Updates View. There are different places in the view where you can find sites to browse. You may have sites in the folder 'Places to visit' or you may have sites on your file system. You can also add some update site if you know their URL.

Browse already existing sites

If you expand the folder 'Places to visit' you may see some sites. They were automatically added to the folder by the feature you installed. You can expand the site and browse the features.

Browse the file system

To browse the file system, expand 'My Computer'.  <TODO what more to say?>

Add a new Update Site

You can add a new update site from the context menu. Select new->SiteBookmark... This opens a Dialog box that presents the properties of the Bookmark Site you want to create. The properties of a Bookmark Site are the label you want to see in the View as well as the Address of the physical site. You have to enter the Site URL. Optionally you can enter the Site Name. If youdo not enter a Site Name, it will default to the Site URL. Click Ok when you have finished and you want to preserve your changes or click Cancel if you do not want to create a new Site Bookmark. Once the site has been created, expand the icon to see the categories and or the available features.

Add a bookmark of a file system site.

When you browse the file syste, you can add a file system site as a bookmark. Select the site. Open the context menu. Select  'Bookmark Location'. This action lets you create bookmark site for a site found on your local file system. This opens a Dialog box that presents the properties of the selected site. The properties of a Site are the label you want to see in the View as well as the Address of the site. You are able to change the Site Name. Click Ok when you have finished and you want to preserve your changes or click Cancel if you do not want to change the properties. Once the site has been created, expand the icon to see the categories and or the available features.

Searching Features

<TODO>

Search for updates

<TODO>

Search the file system

<TODO>

Customize Search

<TODO>

Installing a Feature

This section will describe the Wizard used to install, configure, unconfigure and remove a feature as well as the verification task that may occur when installing a new feature. The first part will focus on the three tab that are part of the Wizard, while the second part will deal with verification and security issues when installing a feature.

Install Wizard

The Wizard will help you install, configure, unconfigure and remove a feature. It will allow you to review any license agreement and to choose the Site in which you wish to install the feature.

The Preview Tab

This tab summarizes the action you are going to take.
Install Wizard Preview Tab PIC002.gif

 The License Tab

This tab will present you the license you have to agree with to install the product. Click on agree if you agree with the whole license and whish to continue or click cancel to abort the installation

Site location Tab

This tab has three main goals. The first one is to show you the available sites on your local file system, the second is the ability to create a new site if the one proposed are not satisfactory, finally you will be able to see the space left on the selected site and the size in kilobyte of the feature you are about to install.

Verification <TODO explain basic certificate >

Verification is an important part of the install process. It will allow you to verify if the feature you are about to install has been digitally signed, not digitally signed or tempered with.
Signed
A dialog with the following <PICTURE> will appear if the feature or one of its file has been signed. A signed feature means the file has been digitally signed by the signer, and the signer has been authenticated by the authenticator. The authenticator can be the same entity as the signer, in which case you will see such a dialog <PICTURE>. In some cases, the authenticator is a different entity than the signer, in which case you will see such a dialog. <PICTURE>. If the authenticator has never been authenticated by you, you will see such a dialog <PICTURE>. If the signature of the authenticator has been authorized before, you will see such a dialog <PICTURE>. Click continue or install only if you trust the signer of the feature file and you want to install the feature, or click cancel if you want to abort the installation.
Non Signed
A dialog  like the following <PICTURE> will appear if the feature or one of its file has not been signed. When a feature has not been signed, we cannot authenticate the sender of the package, nor can we certify the validity of any of the file. Click continue or install only if you want to install the feature, or click cancel if you want to abort the installation.
Corrupted

 If the content of a feature has changed since it has been signed, you will see such a dialog <PICTURE>. This means the content has been tempered with. Install/Update will prevent you from installing such a feature. Click cancel if you want to abort the installation and contact the provider of the feature and/or the site. 

Feature verification dialog

<TODO explain the dialog with feature/ install/ cancel>

Feature file verification dialog

<TODO explain the dialog with feature file/ continue/ cancel>

Persistence of the answer

If click continue or install on a verification dialog, the Install/Update component will remember your action and will not prompt you again if one of the file of the feature is about to show the exact same verification dialog.

Configuring/Unconfiguring a Feature

This section will focus on configuring and unconfiguring the feature you can manage in your current configuration. A configuration is a list of configured and unconfigured features that determine what tool are available for you to use in your workspace.  To know more about configuration see: Configuration .

Checking if a feature is configured or unconfigured.

Feature you installed appear in the Configuration View. Expand the Current Configuration to see the configured sites. Expand the site to see the Features. Use the local view toolbar button to switch between configured features and all the features. Unconfigured features appear with such icon unconf_feature_obj.gif Unconfigured Feature

Configure/Unconfigure Wizard

The Wizard will help you configure or unconfigure a feature.

Preview Tab

This tab summarizes the action you are going to take.
PIC003.gif Configure Wizard Preview Tab

Configuration

A configuration is a list of configured and unconfigured features that determine what tool are available for you to use in your workspace. A configuration determines what task you can execute. There are three types of configuraions: the current configuration, the history configuration and the preserved configuration.

Current Configuration

The current configuration is the configuration currently active.

Configuration History or Preserved Configuration

Configuration History are automatically created by the Install/Update as a snapshot of your current configuration at a certain time, before an activity occurs. Preserved Configuration are configuration in the History Configuration you want to persist.

Configuration History

When you install a feature, the install/update component will copy your current configuration in the history configuration, and then install and configure the feature in you current configuration. You will end up with two configurations, one without the feature installed and configured and one with the feature installed and configured. The install/update will also copy your current configuration when you install or remove a site, when you configure or unconfigure a feature or when a reconciliation is needed. Each actvity will be recorded in the configuration. For each configuration selected in the history configuration folder, you can see in the preview view the list of activities that were executed. See Activities for more information about the different activities.

The install/update will keep a certain number of configuration in the configuration history folder. After this number has been reached, if a new configuration is created, the oldest configuration inside Configuration History folder will be deleted.

Renaming an history configuration

You can rename any configuration in the Configuration History folder. To change the label of a Configuration, select the configuration, open the context menu and click Properties. This will open a dialog where you can change the label of the selected configuration. Click Ok if you want to save the label  or click cancel if you do not want to change the label of the configuration.

Revert the current configuration to the previous configuration

You can revert the current configuration to the previous configuration. <TODO explain better>

 Preserved Configuration

<TODO>

Add a Configuration in the preserved folder

<TODO>

Remove a Configuration in the preserved folder   

<TODO> 

Rename a Preserved Configuration

You can rename any configuration in the Preserved Configurations folder. To change the label of a Configuration, select the configuration, open the context menu and click Properties. This will open a dialog where you can change the label of the selected configuration. Click Ok if you want to save the label  or click cancel if you do not want to change the label of the configuration.


Restore a Configuration/Revert to previous configuration

    <TODO>


The Activities 

Activities are tasks that are part of a configuration. Activities are the actions are were taken to create the Configuration. You can see activities in the preview view when you select a configuration.
activities
Date
The date using the locale format ate which the action took place.
Target
The identifier of the target of the action (see the different type of activities)
Action
The label of the action (see the different types of activities)
Status
The status of the action. Sucess if teh action was sucessful.
There are nine different actions that create an activity in a configuration.

Feature Installed   

When a new feature is installed in a configured site.
The target in the preview view is the identifier of the installed feature.

Feature Removed

When a new feature is physically removed from a configured site.
The target in the preview view is the identifier of the removed feature.

Site Installed

When a Site is added to the current configuration.

The target in the preview view is the Address of the site

Site Removed

When a Site is removed from the current configuration.

The target in the preview view is the Address of the site

Feature Configured

When a new feature is configuredin a configured site.
The target in the preview view is the identifier of the configured feature.

Feature Unconfigured

When a new feature is unconfigured in a configured site.
The target in the preview view is the identifier of the unconfigured feature.

Revert to Configuration

When the user reverted to a configuration from either the configuration history or the preserved configuration

The target in the preview view is the identifier of the configuration we reverted to.

Reconciliation

When the Install/Update detected a changed occured between the last shutdown and this startup.

The URL of the file maintaing the overall configuration.

Added to Preserved Configuration

When a the configuration was added to the list of preserved configurations.

The target in the preview view is the identifier of the configuration added to the preserved configurations.


Removing a Feature

This section explains how to physicaslly remove an Unconfigured feature from the file system. You can only remove unconfigured features. Yo know how to unconfigure a feature see: Configure/Unconfigure Features .

Remove Wizard

This Wizard will help you uninstall an unconfigured feature.
To launch the wizard, select an unconfigured feature in your current configuration. See  Configure/Uncofingue a feature to know how to unconfigure a configured feature, and if a feature is configured or not.

Preview Tab

This tab summarizes the action you are going to take.
uninstall wizard

Troubleshooting

    If the workbench does not start after you installed a new feature.
    The Install/Update views do not show anything.
    I created a Site but nothing shows (verify URL)

Advanced User

    Security and keystore management.