Document new features for ServerManager 2.0

Author: jstetson10

docs/.vscode/settings.json

@@ -1,7 +0,0 @@
-{
-    "objectscript.conn": {
-        "server": "default~iris",
-        "ns": "USER",
-        "active": true
-    }
-}

docs/Configuration.md

@@ -2,12 +2,25 @@
 layout: default
 title: Configuration
 permalink: /configuration/
-nav_order: 3
+nav_order: 4
 ---
-# Configuration
+# Configuration 
 
 VS Code settings enable you to customize various aspects of its function. The InterSystems extensions provide settings used to configure VS Code for ObjectScript development.
 
+{: #code-workspaces}
+## VS Code Workspaces 
+
+To work with VS Code, you need to open a workspace. A VS Code workspace can be just the root folder of your project. Workspace settings and task configurations are stored in the root folder in the `settings.json` file in a folder called `.vscode`. Debugging launch configurations are stored in `launch.json`, also in `.vscode`.
+
+If you need to have more than one root folder in a VS Code workspace, use a feature called multi-root workspaces. See [Multi-root Workspaces](https://code.visualstudio.com/docs/editor/multi-root-workspaces) in the VS Code documentation.
+
+A multi root workspace contains a `*.code-workspace` file. The file can have any name followed by *.code-workspace*, for example `test.code-workspace`. The `*.code-workspace` file stores information about what folders are in the workspace. Other settings that would otherwise be stored in the settings.json or launch.json files can be stored in the `*.code-workspace` file. You can optionally have a workspace file even if you are not using the multi-root feature.
+
+To edit a `*.code-workspace` file in VS Code using the **InterSystems ObjectScript** extension, select **File > Preferences > Settings** (**Code > Preferences > Settings** on Mac) and select the Workspace level. Search for **objectscript: conn**, and click on *Edit in settings.json*. VS Code opens the `*.code-workspace` file for that workspace.
+
+The **InterSystems ObjectScript** extension uses the multi-root workspaces feature to support ObjectScript development on the InterSystems server.
+
 ## Settings
 
 Many available settings are general to VS Code, and you can learn about them in the [Visual Studio Code Documentation](https://code.visualstudio.com/docs). The InterSystems Server Manager and InterSystems ObjectScript extensions supply additional settings you can use to define InterSystems IRIS servers and connections to those servers.
@@ -24,6 +37,7 @@ For example, the following screen shot shows the Workspace level selected:
 
 See the VS Code documentation section [User and Workspace Settings](https://code.visualstudio.com/docs/getstarted/settings).
 
+{: #config-server}
 ## Configuring a Server
 
 First, configure one or more servers. Select **View > Command Palette > InterSystems Server Manager: Store Password in Keychain**. This command lets you define a new server and securely store a password in the system keychain. Click the plus sign in the upper right corner of the dialog, as shown:
@@ -40,6 +54,8 @@ Provide the following values when prompted:
 
 Once you have entered these values, the server definition is stored in your user settings. At that point another prompt appears, asking for a password to store in the system keychain. Enter the password for the username supplied earlier to complete the process. Storing a password is optional. You can terminate the process and store the server configuration by pressing either **Escape** or **Return**. If you do not store a password, users are prompted for a password each time they connect to the server.
 
+To remove a password from the keychain, Select **View > Command Palette > InterSystems Server Manager: Clear Password from Keychain**. The commands to both store and clear passwords are also available from the server context menu in the InterSystems Tools view.
+
 You can create a configuration for a server that is not currently running.
 
 ## Editing a Server Configuration
@@ -50,6 +66,10 @@ If you need to modify a server configuration select **File > Preferences > Setti
 
 Click *Edit in settings.json*.
 
+The InterSystems Tools view provides an alternate path to this `settings.json` file. Click the `...` button and select **Edit Settings**. 
+
+![Edit settings.](../assets/images/edit-settings.png "edit settings")
+
 The server configuration in *settings.json* looks similar to the following, with the values you entered when you configured the server:
 
 ```json

docs/ExtensionUI.md

@@ -0,0 +1,119 @@
+---
+layout: default
+title: InterSystems Extensions UI
+permalink: /extensionui/
+nav_order: 3
+---
+# InterSystems Extensions User Interface
+
+The InterSystems extensions add additional capability to the VS Code user interface to support development in ObjectScript. These additions are based on the standard VS Code UI, which is described in the section [User Interface](https://code.visualstudio.com/docs/getstarted/userinterface) in the VS Code documentation.
+
+## Explorer View
+
+Select the Explorer view button in the Activity Bar to open the view.
+
+![Explorer view button.](../assets/images/explorer.png "explorer view button")
+
+The Explorer view is a standard VS Code view. InterSystems extensions add the following items to context menus in the this view:
+
+- **Add Server Namespace to Workspace...** - in context menu of folders
+- **Import and Compile** - in context menu of folders and files
+- **Import Without Compilation** - in context menu of folders and files
+
+## InterSystems Tools View
+
+The InterSystems Server Manager extension supplies an InterSystems Tools view. Select the InterSystems Tools view button in the Activity Bar to open the view.
+
+![InterSystems Tools button.](../assets/images/intersystems-tools.png "intersystems tools button")
+
+### Viewing Server Resources
+
+This view shows server resources in a tree format.
+
+![Server tree view.](../assets/images/server-tree-view.png "server tree view")
+
+As you can see, the view groups servers into a variety of folders, such as currently in use, favorites, and recently used. Within the view, you can perform operations on the servers. When you move the cursor over a server listing, you see controls to mark the server as a favorite, and open the management portal for the server in either the simple browser in a VS Code tab, or an external browser:
+
+- ![Add to starred.](../assets/images/add-to-starred.png "add to starred")
+- ![Open management portal in tab.](../assets/images/management-portal-tab.png "open management portal the simple browser in VS Code")
+- ![Open management portal in browser.](../assets/images/management-portal-browser.png "open management portal in browser")
+
+Notes About the VS Code Simple Browser
+
+Only one Simple Browser tab can be open at a time, so launching a second server's Management Portal replaces the previous one.
+
+If the server version is InterSystems IRIS 2020.1.1 or later you need to change a setting on the suite of web applications that implement Management Portal. The Simple Browser is not be permitted to store the Portal's session management cookies, so the Portal must be willing to fall back to using the CSPCHD query parameter mechanism.
+
+In the management portal, select **System Administration > Security > Applications > Web Applications**. Enter `/csp/sys` in the **filter** field to find the five web applications whose path begins with `/csp/sys`.
+
+![Portal web app list.](../assets/images/five-web-apps.png "portal web app list")
+
+For each application, select the link in the **name** column to edit the application definition. In the section labeled **Session Settings**, change the the value of **Use Cookie for Session** from **Always** to **Autodetect**. 
+
+![Edit session setting.](../assets/images/edit-webapp.png "edit session setting")
+
+Save the change. This change is not thought to have any adverse effects on the usage of Portal from ordinary browsers, which continue to use session cookies.
+
+### Viewing and Editing Source Code on the Server
+
+Expand the target server, then expand its **Namespaces**  folder. Hover over the target namespace to reveal its command buttons:
+
+![Namespace edit buttons.](../assets/images/namespace-buttons.png "namespace edit buttons")
+
+- Click the **edit pencil** button to add an isfs://server:namespace/ folder to your VS Code workspace.
+- Click the **viewing eye** button to add an isfs-readonly://server:namespace/ folder to your VS Code workspace.
+- Hold the **alt** or **option** key while clicking the edit or view button to add a folder that gives you access to server-side web application files (for example, CSP files).
+
+Once you have added a server-side namespace to the workspace, VS Code opens the Explorer view showing the added namespace. The following screen shot shows the **Sample** and **User** packages in the **src** folder on the client, and the **Sample** and **User** packages in the **USER** namespace on the server, with read-only access.
+
+![Client-side and server-side namespaces.](../assets/images/client-server.png "client-side and server-side namespaces")
+
+Learn more about isfs and isfs-readonly folders in the section [Configuration for Server-side Editing](../serverside).
+
+If you are already doing client-side editing of your code, for example, managing it with Git, be sure you understand the consequences of also doing server-side editing using isfs. The ObjectScript extension's README outlines the differences between client-side and server-side editing. If in doubt, limit yourself to isfs-readonly by only using the eye icon.
+
+### Adding a Server
+
+You can use the plus sign (`+`) at the top of the view to add a server. This control provides an additional entry point to the process described in the section [Configuring a Server](../configuration/#config-server).
+
+![Add server.](../assets/images/add-server.png "add server")
+
+The server definition is added to your user-level *settings.json* file and also appears at the top of the 'Recent' folder.
+
+### Server Context Menu
+
+Servers listed in the InterSystems Tools view provide a context menu which provides access to several commands, including storing and clearing passwords in the keychain.
+
+![Server conext menu.](../assets/images/server-context-menu.png "server context menu")
+
+A submenu enables you to set the color of the icon to the left of the server name. The following screen shot shows this menu, and the icon color set to red.
+
+![Set icon color.](../assets/images/set-icon-color.png "set icon color")
+
+### Import Server Connections
+
+On Windows, the Server Manager can create connection entries for all connections you previously defined with the original Windows app called InterSystems Server Manager. This action is available from the '...' menu at the top right corner of Server Manager's tree, as shown in the following screen shot.
+
+![Import servers from registry.](../assets/images/import-servers.png "import servers from registry")
+
+## ObjectScript View
+
+The InterSystems ObjectScript extension supplies an ObjectScript view. The button to select this view appears in the Activity Bar only when a workspace or folder is open:
+
+![ObjectScript button.](../assets/images/objectscript.png "objectscript button")
+
+When a VS Code workspace is not connected to an InterSystems IRIS server, the ObjectScript view provides a button that lets you select a server and namespace. Once the workspace is connected to an InterSystems IRIS server, the ObjectScript view shows files on the server, grouped by type of file.
+
+If the workspace is configured for server-side editing, the ObjectScript view is not available. In this configuration, the Explorer view lists files on the server, not on the local machine, making the ObjectScript view irrelevant.
+
+The ObjectScript view provides the following items:
+
+- **Compile** - Compiles files on the server.
+- **Delete** - Deletes files from the server.
+- **Export** - Exports files to the workspace on the client.
+- **Server Command Menu...** - Pick a command from menus configured on the server.
+- **Server Source Control...** - Pick a command from menus configured on the server.
+
+The InterSystems IRIS documentation section [Extending Studio](https://docs.intersystems.com/irislatest/csp/docbook/Doc.View.cls?KEY=ASC#ASC_Hooks_extending_studio ) describes how to configure menus for source code control and other purposes. Entries from menus named **%SourceMenu** and **%SourceContext** appear in the **Server Source Control...** quickpick provided the source control class doesn't disable the entry, for example, disabling checkout if it knows that the file is already checked out.
+
+Entries from menus with any other name appear in the **Server Command Menu...**.

docs/Installation.md

@@ -8,11 +8,11 @@ nav_order: 2
 
 ## Install VS Code
 
-Your first step is to install VS Code: 
+Your first step is to install VS Code:
 
 1. Go to the [Visual Studio Code download page](https://code.visualstudio.com/).
-2. Download an appropriate build for your platform.
-3. Open the downloaded file and follow the installation instructions.
+1. Download an appropriate build for your platform.
+1. Open the downloaded file and follow the installation instructions.
 
 ## Install the InterSystems ObjectScript Extensions
 
@@ -30,6 +30,4 @@ Type `intersystems` in the search field to find these extensions in the Marketpl
 
 ![Search in Marketplace.](../assets/images/marketplace.png "search in marketplace")
 
-You can install all the required extensions in one step by clicking on the **Install** button for the InterSystems ObjectScript Extension Pack. You can also install each extension separately by clicking the **install** button for the required extension. Note that the InterSystems ObjectScript extension supplies an ObjectScript button which appears in the Activity Bar when a workspace or folder is open:
-
-![ObjectScript button.](../assets/images/objectscript.png "objectscript button")
+You can install all the required extensions in one step by clicking on the **Install** button for the InterSystems ObjectScript Extension Pack. You can also install each extension separately by clicking the **install** button for the required extension. 

docs/RunDebug.md

@@ -2,7 +2,7 @@
 layout: default
 title: Running and Debugging
 permalink: /rundebug/
-nav_order: 4
+nav_order: 5
 ---
 # Running and Debugging
 

docs/ServerSide.md

@@ -2,22 +2,10 @@
 layout: default
 title: Server-side Editing
 permalink: /serverside/
-nav_order: 5
+nav_order: 6
 ---
-{: #code-workspaces}
-# VS Code Workspaces 
 
-To work with VS Code, you need to open a workspace. A VS Code workspace can be just the root folder of your project. Workspace settings as well as debugging and task configurations are stored in the root folder in a folder called .vscode.
-
-If you need to have more than one root folder in a VS Code workspace, use a feature called multi-root workspaces. See [Multi-root Workspaces](https://code.visualstudio.com/docs/editor/multi-root-workspaces) in the VS Code documentation.
-
-A multi root workspace contains a \*.code-workspace file. The file can have any name followed by *.code-workspace*, for example `test.code-workspace`. The .code-workspace file stores information about what folders are in the workspace. Other settings that would otherwise be stored in the settings.json or launch.json files can be stored in the .code-workspace file. You can optionally have a workspace file even if you are not using the multi-root feature.
-
-To edit a *.code-workspace* file in VS Code using the **InterSystems ObjectScript** extension, select **File > Preferences > Settings** (**Code > Preferences > Settings** on Mac) and select the Workspace level. Search for **objectscript: conn**, and click on *Edit in settings.json*. VS Code opens the *.code-workspace* file for that workspace.
-
-The **InterSystems ObjectScript** extension uses the multi-root workspaces feature to support ObjectScript development on the InterSystems server.
-
-# Configuration for Server-side Editing
+# Configuration for Server-side Editing 
 
 You can configure the InterSystems ObjectScript extension to edit code directly on the server, using the [multi-root workspaces](https://code.visualstudio.com/docs/editor/multi-root-workspaces) VS Code feature. This type of configuration is useful in cases where source code is stored in a Source Code Management (SCM) product interfaced to the server. For example you might already be using the Source Control menu in InterSystems Studio or Portal, implemented by a source control class that extends `%Studio.SourceControl.Base`.
 
@@ -44,13 +32,13 @@ Next create a workspace for editing code directly on the server:
 
 Note that the ObjectScript button is not visible in the Activity Bar, because the files listed in the Explorer view are all on the server, so it is not needed for this configuration.
 
-The `.code-workspace` file is a JSON file which you can edit directly, as described in the section  [VS Code Workspaces](#code-workspaces). A simple example looks like this:
+The `.code-workspace` file is a JSON file which you can edit directly, as described in the section  [VS Code Workspaces](../configuration/#code-workspaces). A simple example looks like this:
 ```json
 {
 	"folders": [
 		{
 			"name": "iris184:USER",
-			"uri": "isfs://iris184:user/"
+			"uri": "isfs://iris184:user"
 		}
 	],
 	"settings": {}
@@ -59,8 +47,10 @@ The `.code-workspace` file is a JSON file which you can edit directly, as descri
 - The `name` property provides a name for this server-side folder.
 - The `uri` property indicates the location of resources on the server. The supplied value has three components:
    - The first component can be either `isfs` or `isfs-readonly`. These values specify that this folder is on an InterSystems IRIS server. `isfs-readonly` specifies read-only access.
-   - The value following `://` specifies the name of the server.
-   - The value following the next `:` specifies the namespace (lowercase).
+   - The value following `/` specifies the name of the server.
+   - The value following `:` specifies the namespace (lowercase).
+
+The string `isfs` which appears in the **uri** for folders configured for server-side editing is an abbreviation created by InterSystems which stands for **InterSystems File Service**. It implements the VS Code [FileSystemProvider API](https://code.visualstudio.com/api/references/vscode-api#FileSystemProvider), which let's you make any remote location look like a local one. It was designed for common things like FTP servers, but it works well for making artefacts in an InterSystems IRIS database namespace look like local files.
 
 To add more root folders to your workspace, giving you access to code in a different namespace, or on a different server, use the context menu on your existing root folder to invoke the `Add Server Namespace to Workspace...` command. This command is also available on the Command Palette.
 
@@ -70,11 +60,11 @@ An example of a two-folder workspace in which the second folder gives read-only
 	"folders": [
 		{
 			"name": "iris184:USER",
-			"uri": "isfs://iris184:user/"
+			"uri": "isfs://iris184:user"
 		},
 		{
 			"name": "iris184:%SYS (read-only)",
-			"uri": "isfs-readonly://iris184:%sys/"
+			"uri": "isfs-readonly://iris184:%sys"
 		}
 	],
 	"settings": {}