Deltanji source control

Deltanji from George James Software provides effective configuration management, versioning, and process control within development teams. This provides clear visibility of the development process and, in turn, improves the code quality and maintainability of your system. It can be configured to suit your needs, whether you're an individual developer or part of an international organization.

This is the Deltanji client integration for VS Code. It operates seamlessly with Serenji debugger, and also with the InterSystems ObjectScript extension.

Installation

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

We also recommend installation of the InterSystems Server Manager extension so the Deltanji extension can use it for secure password storage.

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

If you want to evaluate Deltanji, install the Serenji extension which bundles Deltanji Solo edition. Then follow Serenji's setup instructions to prepare your InterSystems environments to work with Serenji.

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. If you have also installed the InterSystems Server Manager extension you can opt to use this for secure password storage. Otherwise your credentials can be saved as plaintext 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.

Secure Password Storage

By using the 'InterSystems Server Credentials' authentication provider service, implemented in version 3 of the InterSystems Server Manager extension, the Deltanji extension can connect to its server without prompting for a password each time or storing the password as plaintext in your settings file.

To use this capability:

Install Server Manager if you don't already have it.
In the InterSystems Portal of the server hosting Deltanji, check that the /api/atelier web application does not permit 'Unauthenticated' access. At least one other authentication method should be enabled, typically 'Password'.
Open your user settings file (Preferences: Open User Settings (JSON) from Command Palette) and search for "deltanji.servers". If this object exists and contains an entry matching the URL of your Deltanji browser UI (e.g. "https://devapps.acmecorp.com/deltanji/Client.VCm.cls"), delete the following property lines that may exist under it:
- username
- password
- saveCredentials
Reload your VS Code window (Developer: Reload Window command). When the Deltanji extension tries to connect and doesn't find a matching Server Manager connection definition you will be prompted to create this. After clicking 'Yes' to confirm, complete the prompt sequence at the top of the window. When prompted for the password, type it and store it by clicking the 'key' button in the upper right corner of the prompt.
When asked to permit the Deltanji extension to sign in using InterSystems Server Credentials, click 'Allow'. The Deltanji output channel will report the usual messages, e.g.

Deltanji connected to https://devapps.acmecorp.com/deltanji/Client.VCm.cls as user jdoe
  Extension: 1.2.6
     Server: 7.0 Enterprise edition (#210014)
       Host: IRIS for UNIX (Ubuntu Server LTS for x86-64) 2021.1.2 (Build 338U) Tue Apr 12 2022 12:04:54 EDT
 - Fetching configuration data
 Ready

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:

Using InterSystems Portal on the Deltanji host, review the definition of the Deltanji web application (typically /deltanji). If it includes a checkbox setting labeled Prevent login CSRF attack make sure this is unchecked.
If the Deltanji web UI is being hosted over https using a web server with a self-signed or locally-signed certificate, the Deltanji extension needs to be told that it can ignore the fact that the security of its communication with Deltanji will be degraded. Text transferred over the wire will still be TLS-encrypted, but the identity of the target server cannot be verified.

A user-level or workspace-level (but not folder-level) setting called rejectUnauthorized must be set false within the deltanji.servers object, in a child object whose name corresponds to your ^%vcvc("browserUrl") global node value, e.g.

	"deltanji.servers": {
...
		"https://devapps.acmecorp.com/deltanji/Client.VCm.cls": {
			"rejectUnauthorized": false
		},
...
	},

If you are using the InterSystems ObjectScript extension for server-side code editing (isfs):
- Create the following VS Code setting, amending the actual value to match the contents of your ^%vcvc("browserUrl") node:
```
"deltanji.serverURL": "https://devapps.acmecorp.com/deltanji/Client.VCm.cls"
```
If you only work with one Deltanji instance you can set this at the user level. Otherwise set it at the workspace level. Or if you want to make the setting once per namespace and have it available to all users who connect there, enable server-side configuration first.
- If the namespace your isfs uri connects to corresponds to a Deltanji location whose M-format storage uses a task server address (e.g. ,DEV,ENSDEMO,/databases/DEV/DELTANJI-LOCAL) then you must also set deltanji.myNodeNames to inform the Deltanji extension which ECP connection the task server address uses, e.g.
```
"deltanji.myNodeNames": [
    "DEV"
]
```
Note how this setting is structured as an array of strings in order to cater for certain configurations not described here.

If you are using a multi-root workspace accessing namespaces on different servers you will need to configure deltanji.myNodeNames at the folder level. Doing this requires the additional server-side configuration mentioned above.
- Close and reopen your VS Code workspace after making these settings.
Alternatively, if you are using the Serenji extension for code editing:
- In your DELTANJI namespace, issue the following commands:
```
DELTANJI>set ^%vcFilestore("roots",".serenji")=""
DELTANJI>set ^%vcFilestore("roots",".vscode")=""
```
- 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.acmecorp.com' running the service on port 2021:
```
    "serenji.servers": {
        "deltanji": {
            "host": "deltanji.acmecorp.com",
            "port": 2021
        },
    },
```
You may also want to add a value for the username property, and optionally a password.
- Create a VS Code workspace that connects to this server using Serenji, either at the root level or explicitly to one or more namespaces.

When you open a file within a Deltanji-managed namespace you should see a message in the Deltanji channel of the Output tab of the VS Code Panel 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 for Serenji Users

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 you 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.

Quick Diff

In order to display quick diff editor gutter decorations your Deltanji Diff Server (%vc830) must be able to operate in passive mode. This extension always uses EPSV mode, so if your server firewalling blocks the incoming data channel connections you will not see these decorations.

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.

Showing Extra Locations

The Source Control view automatically includes a section for each Deltanji-controlled namespace you open code in. To show additional sections for other Deltanji locations, add the locations to a comma-separated list in the otherLocations property of the deltanji.servers child object corresponding to your server. For example:

"deltanji.servers": {
...
    "https://devapps.acmecorp.com/deltanji/Client.VCm.cls": {
...
        "otherLocations": "APP1.ReadyForTest,APP1.InTest",
...
    },
...
},

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.85.2
common.extversion 1.2.6
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.1
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 version 1.2.6.

See the Changelog for details.

Support

Email support@georgejames.com