Deltanji 1.1 Pre-Release

Deltanji from George James Software (GJS) is an extension for Visual Studio Code (VS Code) providing Source Code Control for classes, routines, CSP pages and many other kinds of file used in InterSystems environments.

Deltanji is fully integrated with VS Code and operates seamlessly with Serenji, the VS Code extension for editing and debugging ObjectScript code.

Pre-Release Details

This pre-release requires VS Code 1.63 or later.

By using the 'InterSystems Server Credentials' authentication provider service implemented in version 3 of the InterSystems Server Manager extension (currently a pre-release), the Deltanji extension can connect to its server without prompting for a password or storing the password insecurely in a settings file.

To configure this:

1. Note the URL with which you access your Deltanji browser UI. For example http://dem:52773/deltanji/default.htm or http://dem:52773/deltanji/Client.VCm.cls

2. After installing the InterSystems Server Manager extension, use it to define a server with these characteristics:

   • Server name matches the hostname part of your Deltanji URL. If the hostname includes '.' characters, these are replaced with '-' in order to conform to Server Manager naming rules.
   • Port matches that of the URL, or the URL does not specify a port explicitly.
   • Protocol (http or https) matches.
   • Username is the one you use in Deltanji.

   For example, define a server named dem connecting to port 52773 using http as user jdoe.

3. If the target InterSystems server was installed with a security level of 'Minimal', use Portal to adjust the configuration of the /api/atelier web application so it requires Password authentication and disallows Unauthenticated access.

4. In Server Manager, expand your new server's Namespaces folder. When prompted for the username's password, type it and store it by clicking the 'key' button in the upper right corner.

The first time you open a file in a Deltanji-controlled workspace after completing the above steps you will be prompted to permit the Deltanji extension to sign in using InterSystems Server Credentials. Click 'Allow', then confirm the account you want to use (e.g. 'jdoe on dem'). The Deltanji output channel will report the usual messages, e.g.

Deltanji connected to http://dem.acmecorp.local:52773/deltanji/Client.VCm.cls as user jdoe
  Extension: 1.1.2021121001
     Server: 7.0 Enterprise edition (#210014)
       Host: IRIS for UNIX (Ubuntu Server LTS for x86-64) 2019.1 (Build 510_4U) Thu Jun 13 2019 15:39:04 EDT
 - Fetching configuration data
 Ready

Installation

From VS Code's Extensions view, search for the Deltanji extension and install it.

If you haven't already installed the Serenji extension it will be added to VS Code automatically. Then you must follow Serenji's setup instructions to prepare your InterSystems environments to work with Serenji.

If you want to use the Deltanji Solo edition that is pre-installed with Serenji then no additional configuration is required. Deltanji Solo is ready to use.

If you want to use an existing Deltanji Team or Deltanji Enterprise edition, consult the section below for instructions.

Unless you have disabled VS Code's telemetry feature, this extension will send some usage data to GJS. For more details consult the section below.

Usage

In Brief

Browse and view files as normal. When you first open a file this extension will attempt to make a connection to the appropriate Deltanji server. You will be prompted for your authentication credentials at this point. These can be saved in your user settings file to avoid having to enter them again. Once a connection has been established, Deltanji will report the status of the file you just opened.

When you edit a file Deltanji will check it out by creating a local copy with its own unique version number. It will also associate the file with a Change Request. A Change Request is a container for a set of related changes to one or more files. Typically a Change Request represents a project, a ticket or other piece of work. If you have not set up any Change Requests you can use Change Request 1, which is pre-defined in Deltanji Solo.

When you have completed some changes you can check in your files by right-clicking and selecting Check In. Alternatively, you can check in all the files on a change request by navigating to the Source Control viewlet (Ctrl+Shift+G) selecting the change request and clicking the Check In button.

Change Request

All changes must be linked to a Change Request. A Change Request is an identifier for a project or ticket that you are working on. You can create a Change Request using Deltanji's browser interface. When you edit a file for the first time you will be prompted for a Change Request. You can set a default Change Request that will be used automatically by navigating to the Source Control viewlet and clicking the Favorite button against a Change Request.

Check Out

When you make a change to a file, class or routine the file will be assigned a unique version number which is used to record and track this version of the file through its complete lifecycle.

New files must be registered if you want Deltanji to keep track of them. VS Code can be configured to do this automatically, or you can register a file at any time by right-clicking and selecting Register. All new files need to be associated with a System code, which can be used to subdivide a repository into separate groups corresponding to systems, namespaces, packages or applications. If a namespace is configured to permit multiple Systems then you may be prompted for a System code at this point. This will be remembered and used for subsequent new file registrations.

Check In

When you have finished making changes to your file you can check it in to the repository. Once checked in no further changes are possible for that version of the file. Any subsequent changes will be made to a new version of that file.

Transfer

Depending on your Deltanji configuration you may be able to copy your changed file to another location for testing or staging or some other purpose. You can do this by right-clicking in the editor and selecting Transfer. This will copy the file to the test or staging location and compile it if necessary. You may also transfer a file by selecting Transfer from the file's context menu in VS Code's file explorer, or by navigating to the Source Control viewlet, selecting one or more files or change requests and then clicking the Transfer icon.

Depending on your configuration, there may be more than one permitted transfer location. In this case you will be able to select from a pick list showing all available destinations. Transfer routes are a major feature of Deltanji that enable complex workflows and automation.

Cancel

If you want to revert your changes without checking them in, you can cancel them. This will delete the current version and reinstate its predecessor.

Source Control Viewlet

The Source Control Viewlet shows all the files that you have checked out. Each namespace is shown in a separate panel and within that each checked-out file will be listed by Change Request. Namespaces will only be listed once you have opened at least one file in that namespace.

Show all/my Change Requests

By default only files belonging to Change Requests owned by you will be shown. You can toggle this view to show files belonging to all Change Requests.

Select Systems to associate with new file registrations

When a new file is registered with Deltanji it needs to be associated with a System code. This can be used to subdivide a repository into separate systems, packages or applications. If a namespace is configured to permit multiple Systems then you can use this setting to select the System codes that will be used for new file registrations in this namespace.

Namespaces

Each namespace in which you have opened at least one file will be listed in the Source Control viewlet as a separate Source Control Provider. You may have namespaces opened from more than one IRIS server and each server can have a different instance of Deltanji managing it.

Change Requests

Within each namespace all Change Requests containing checked-out files are listed. If multiple users are working on different projects within a single namespace then you can choose to show all checked-out Change Requests or just those that are owned by you.

Files

All checked-out files belonging to each Change Request are listed along with their variant code and version number in square brackets. Variant codes are typically the same as the file's System code and identify the namespace, system, package or application that the file belongs to. Version numbers begin at 0 for new files and are incremented each time a file is checked out to be edited.

Version numbers are typically sequential, but there may be gaps if a version is cancelled. Version numbers may also be non-contiguous if the file has been branched or merged.

For each Change Request you can toggle the display to list just the checked-out files or you can see all the files that belong to it.

Deltanji Team and Enterprise Editions

For use with Deltanji Team and Enterprise editions this extension requires Deltanji version 7.0 or later.

To configure your Deltanji instance for first use by VS Code, follow these steps:

1. In your DELTANJI namespace, issue the following commands:

   DELTANJI>set ^%vcFilestore("roots",".serenji")=""
   DELTANJI>set ^%vcFilestore("roots",".vscode")=""
   

2. In your VS Code user settings (settings.json file) define a Serenji connection to your Deltanji diff server, which is also knows as the Beyond Compare server (%vc830). The status and port number of the diff server can be found by running the following command in your DELTANJI namespace:

   DELTANJI>do ^%Serenji
   ...
   Serenji explore/edit/debug service
   (hosted by Deltanji Version 7.0)
   ----------------------------------
   Service status: Running
   Primary port: 2021
   Aux port min: 0
   Aux port max: <unset>
   Server address: <unset>
   ...
   

   Below is an example of a connection definition for a Deltanji on host 'deltanji.mydomain' running the service on port 2021:

    "serenji.servers": {
        "deltanji": {
            "host": "deltanji.mydomain",
            "port": 2021
        },
    },
   

   You may also want to add a value for the username property, and optionally a password.

3. Create a VS Code workspace that connects to this server, either at the root level or explicitly to one or more namespaces.

When you open a file within a namespace you should see a message telling you the Deltanji status of the associated component.

If you need assistance making this work, email support@georgejames.com for help.

Additional Deltanji Settings

• To benefit from syntax-aware handling of classes, Deltanji should be handling CLS components in UDL format rather than XML format. For InterSystems platforms on Windows, UDL is available from 2014.1 upwards. On Linux and similar 2016.1.1 is required. UDL is not available on OpenVMS. To enable UDL mode, set these nodes:

  DELTANJI>set ^%vcct("CLS","settings","useUDL")=1
  DELTANJI>set ^%vcct("CLS","settings","getLibraryXMLasUDL")=1
  

• If you work with MAC routines, issue the following command to yield extra information about post-save compilation errors, and to allow INT-code debugging:

  DELTANJI>if $get(^%vcct("MAC","settings","compileFlags"))'["k" set ^%vcct("MAC","settings","compileFlags")=$get(^%vcct("MAC","settings","compileFlags"))_"k"
  

• If your work with text or binary files (T and BIN components in Deltanji) but do not see these files listed in VS Code, email support@georgejames.com for assistance.

Transfer Routes

The Deltanji VS Code extension will use existing transfer routes to perform Register, Check Out, Check In and Transfer operations. It uses the following route definitions for each of these operations:

Register

When a previously unmanaged file is added to source control, any transfer route with a function code of REGISTER and both from- and to-location of this namespace can be used. If there is more than one possible route you will be presented with a list of routes to choose from.

Check Out

When a file is changed in a namespace, or if a Check Out is explicitly requested, any transfer route with a function code of OUT and a to-location of this namespace can be used. If there is more than one possible route you will be presented with a list of routes to choose from.

Check In

When a Check In is performed for a file in a namespace, any transfer route with a function code of IN and a from-location of that namespace can be used. If there is more than one possible route you will be presented with a list of routes to choose from.

Transfer

When a Transfer is performed for a file in a namespace, any transfer route with a function code of XFER and a from-location of this namespace can be used. If there is more than one possible route you will be presented with a list of routes to choose from.

Systems

If a location is configured to permit multiple Deltanji Systems, then when a new file is registered for the first time in its namespace you will be prompted with a list of Systems and must choose which ones to associate with the file. This choice will be remembered in your user settings and will be used for all subsequent file registrations in that namespace. If you want to change your choice you can edit your user settings.json file.

Telemetry

This extension uses the vscode-extension-telemetry module to report usage data to a Microsoft Azure Application Insights (AppInsights) endpoint controlled by George James Software. An example of the custom datapoints:

• common.platformversion 10.0.18363
• common.vscodesessionid someValue.sessionId
• common.vscodemachineid someValue.machineId
• common.vscodeversion 1.63.0
• common.extversion 1.1.2021121001
• common.extname vscode-deltanji
• common.os win32
• deltanji.hostVersion IRIS for Windows (x86-64) 2018.1.2 (Build 626_3U) Wed Jun 12 2019 19:07:59 EDT
• deltanji.version 7.0
• deltanji.license 212409
• authenticationMethod IRIS

AppInsights also provides geolocation data.

You can disable all telemetry output from VS Code by setting "telemetry.enableTelemetry": false

Release Notes

This is a version 1.1 pre-release.

See the Changelog for details.

Support

Email support@georgejames.com