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.
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:
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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:
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 email@example.com for help.
Additional Deltanji Settings
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:
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.
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.
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.
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.
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
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:
AppInsights also provides geolocation data.
You can disable all telemetry output from VS Code by setting
This is a version 1.1 pre-release.
See the Changelog for details.