Serenji from George James Software (GJS) is an extension for Visual Studio Code (VSCode), allowing you to edit and debug InterSystems ObjectScript code directly in the namespaces where that code executes. No exporting and importing of files is necessary.
Serenji includes an embedded edition of the Deltanji source code management product from GJS. A separate VSCode extension integrates Deltanji with VSCode as a source control provider that you can interact with from the Source Control viewlet. Contact GJS for more information about that extension. You can also access Serenji's embedded Deltanji through its web browser UI.
Use the Extensions viewlet in VSCode (Ctrl/⌘+Shift+X) to search for Serenji and install it.
Alternatively, download it as a VSIX file from https://georgejames.com/files/vscode-serenji-3.0.2.vsix and use the "..." menubutton in upper right corner of the Extensions viewlet to choose "Install from VSIX..."
To edit and debug code on an InterSystems environment you must first prepare it. Eligible environments must be running InterSystems IRIS Data Platform (herafter abbreviated as 'IRIS'), or Cache, Ensemble or HealthShare. The minimum InterSystems version supported by the standard extension kit is 2009.1. If you need support for earlier versions, email support@georgejames.com for advice.
The following instructions apply to all supported environments. They should also be followed to upgrade Serenji software on environments previously set up for use with an earlier version of this extension.
References to IRIS apply equally to Caché, Ensemble and HealthShare environments.
Proceed as follows:
Download the server-side components to your server from this link: https://georgejames.com/files/Serenji-3.0.2.zip
Unzip it. The zip contains a filetree rooted in a directory called Serenji.
Move the unzipped Serenji directory to where you want the software to be located long-term. On a Windows host this could be C:\Serenji. We recommend you avoid putting it under C:\Program Files\ as, depending on your exact configuration, that location may cause permission issues during the installation.
Open a Terminal session in IRIS, authenticating as a user with maximum privileges (e.g. holding the %All role), such as SuperUser. This level of permission is necessary so that the install script can add a namespace, a database and a web application to your IRIS configuration.
Optionally, enable terminal logging in case you have installation problems and need advice from GJS. If you are using InterSystems Terminal use the Logging... option on Terminal's File menu.
The next step imports and compiles a class called Serenji.Installer. This contains a classmethod that you will later run to create a database for the Serenji code and the embedded Deltanji source control repository. The Serenji.Installer class can be loaded into any existing namespace. We suggest you use the USER namespace if it is available.
Switch to the USER namespace. Load and compile the class from the Serenji.Installer.xml file in the directory of your unpacked Serenji kit, e.g.
%SYS>zn "USER"
USER>d $system.OBJ.Load("C:\Serenji\Serenji.Installer.xml","c")
Now invoke its RunInstall method, passing as a parameter the path to the root of your Serenji kit, e.g.
USER>d ##class(Serenji.Installer).RunInstall("C:\Serenji\")
When this completes, turn off terminal logging if you previously enabled it.
Review the output for any error messages. If you are unsure whether the installation succeeded, contact support@georgejames.com
You may now tidy up by deleting the Serenji.Installer class from the namespace you imported and ran it in, e.g.
USER>d $system.OBJ.Delete("Serenji.Installer.cls")
If your target environment is a failover member of an InterSystems mirroring configuration you will probably want to add the SERENJI database, namespace and other settings to the other failover member so that it can host your editing and debugging whenever it takes over as master.
The Serenji Service is an ObjectScript process (%Serenj830) that must be running before the Serenji extension can connect VSCode to that InterSystems environment.
Start it in the SERENJI namespace which was created when you installed the Serenji software on the environment. An interactive startup asks what port it should listen on (default is 43211) and what port range to use for the inbound data connection (default is the single port 43212):
USER>zn "serenji"
SERENJI>d Service^%Serenji
Tips:
do ServiceStart^%Serenji or job ServiceStart^%Serenjido ServiceStop^%SerenjiWrite $$ServiceStatus^%Serenji$USERNAME that the service process runs as must hold WRITE permission on the resource protecting the CACHESYS / IRISSYS database. This permission allows it to call $SYSTEM.Security.Login(user) without a password after getting user from the client-side keyfile.%Serenj830.Follow these steps to prepare your VSCode environment for editing code in your InterSystems server environment.
Add a section of JSON to User Settings. One way to access this is:
F1 or Ctrl/⌘+Shift+PBelow is an example of a connection definition for a local InterSystems environment running the Serenji Service on port 43211:
"serenji.servers": {
"tin.iris181": {
"host": "127.0.0.1",
"port": 43211,
"username": "SuperUser",
"password": "SYS"
},
},
Highlight the above block. Copy it using Ctrl/⌘+C. Position the cursor at the end of line 1 of your settings.json file. Press Enter to add a new line. Paste using Ctrl/⌘+V.
tin.iris181 which is a lowercase variant of the $SYSTEM variable of the target environment, with . substituted for :. This is our recommended naming convention. You can name your connections other ways if you prefer, but connection names must consist only of lowercase a to z, digits, underscore, minus and dot characters.username and password will be used to negotiate InterSystems security (equivalent to authenticating from Portal, Studio, Atelier etc). On a target environment installed with the Minimal Security option, default valid credentials suitable for use here are SuperUser and SYS as shown.username element is omitted or set to "" you will be prompted to enter one upon first connection to the target in a VSCode session.SerenjiUser role or the %All role.password element if you don't want to store it in plaintext in your VSCode Settings file. You will then be prompted for your password the first time it is needed in a VSCode session.Remember to save the modified settings.json file (Ctrl/⌘+S).
A workspace specifies which server(s) you will work on, and which namespace(s).
Ctrl/⌘+K followed by F).F1 or Ctrl/⌘+Shift+PIn the VSCode Explorer viewlet (Ctrl/⌘+Shift+E) expand the workspace tree. If you didn't restrict your folder to a single namespace, expand one of the listed namespaces to find routines and classes that you can open. Any changes you make to them here will be written to the namespace as soon as you save them within VSCode. Compilation happens immediately after saving, and compilation errors appear in the Problems panel.
The tree does not show generated code (e.g. INTs generated from CLS or MAC definitions), or code that is not stored in the namespace's default database (mapped code).
Consider enabling VSCode breadcrumbs via the View menu so you can easily jump to methods, properties and line labels in your code. The Outline section of VSCode Explorer also lets you do this, and the '...' button on the Outline header gives you extra control of the order in which the items appear.
To create a new class or routine, right-click at the appropriate place in the tree (e.g. on the desired namespace if your folder is giving you a multi-namespace view of your server), then choose 'New File'. Enter the required name, which must include the appropriate suffix (.cls, .mac, .inc or .int).
The initial contents of a new file come from one of the template files that are located in the .serenji subfolder of your workspace root. You can edit these templates. You can also create copies of these in the XXX\.serenji subfolder of your XXX namespace if you need namespace-specific templates for new files.
To help with class editing Serenji provides default snippets which add properties and methods. Access these as usual in VSCode by typing Ctrl/⌘+space, then start typing method or property. After selecting a snippet, use the Tab key to move between fields within it.
A class or routine can be deleted from within VSCode. Be aware that this action will immediately delete the item from the namespace on your server. CAUTION: VSCode might misleadingly advise you that it is going to move the document to the Trash / Recycle Bin and that you will be able to restore it from there. This is cause by a VSCode bug. In fact the deletion will be permanent, with no way of undoing it.
One way of protecting your server code is to register it for management by the Deltanji source control bundled with Serenji. You can launch the Deltanji UI from the Command Palette using Serenji: Open Deltanji in Web Browser.
To use the debug features of Serenji you will need a keyfile issued by George James Software. Each keyfile unlocks debugging for a named user on a specific InterSystems environment.
Without a keyfile you can only use Serenji to view and edit code.
Keyfiles are only issued for identifiable individuals. They are not available for generic usernames such as 'Admin', 'SuperUser', '_SYSTEM' etc.
Connect Serenji to the target environment using the username you want to debug as. This user will require the %Development:Use privilege. This typically comes from the user having been assigned the %Developer role.
Expand the workspace root, e.g 'Serenji: tin.iris181'
Expand the .serenji folder.
Open the file named registrationData.txt (the contents are generated dynamically when opened).
Copy the contents of this file into an email to admin@georgejames.com requesting a Serenji key. Please give your email the subject line Serenji License Key request.
An example of the contents:
Version: 3.0.0
Username: me
HostKey: lYOmLEHkf8DTsC3CxoUKpJR5ums
System: TIN:IRIS181
Platform: IRIS for Windows (x86-64) 2018.1.2 (Build 609U)
Now: 2019-03-05T16:58:49+00:00
If your registration data indicated that your InterSystems environment is mirrored, also include in your email the Serenji registration data from the failover member (if you have one) by logging into Terminal with the same username and then running the following command in the SERENJI namespace of the failover environment:
Do ^%Serenji
Wait for an email response telling you how to collect your keyfile. Please note that the response is manually created by GJS personnel during UK business hours.
Follow the instructions in that email to download your keyfile and save it.
Add a license object property to the entry you previously defined in serenji.servers in your User Settings (JSON view). For example, if you named your Serenji connection tin.iris181 and you saved your keyfile as C:\Users\me\Documents\SerenjiKeys\me-TIN-IRIS181.p12 your augmented serenji.servers setting should look something like this:
"serenji.servers": {
"tin.iris181": {
"host": "127.0.0.1",
"port": 43211,
"username": "me",
"password": "secret",
"license": {
"keyfile": "C:\\Users\\me\\Documents\\SerenjiKeys\\me-TIN-IRIS181.p12"
}
},
},
Note how backslashes must be doubled in JSON string values.
Serenji uses native InterSystems debug facilities, and these require INT code to exist. In view of this, when you edit and save a class or a routine with Serenji the post-save compile retains INT code by default. However if you want to debug code that hasn't been changed through Serenji you may first need to recompile it and specify the "k" flag for the compilation.
Ctrl/⌘+Shift+D) use the configuration selector dropdown to choose a 'Routine' entry. Then click the adjacent green 'go' button.USER (this can also be entered in lowercase).INT^%TCtrl/⌘+Shift+D) use the configuration selector dropdown to choose a 'ClassMethod' entry. Then click the adjacent green 'go' button.USER (this can also be entered in lowercase).%Library.PopulateUtils.City(). This format is more concise than the conventional ##class format.Ctrl/⌘+Shift+D) use the configuration selector dropdown to choose an 'Existing Process' entry. Then click the adjacent green 'go' button.--publish 43211-43212:43211-43212 to your docker run command. You must also set the global node ^%Serenjvc("ftpServer","serverAddress") so it contains the IPv4 address at which VSCode can reach your Docker host. In the simple case where you are running VSCode on the Docker host, the following command in the SERENJI namespace is suitable: set ^%Serenjvc("ftpServer","serverAddress")="127.0.0.1"You may wish to take some of the following extra steps.
Add code to your InterSystems environment that will autostart the Serenji Service process on startup. We recommend using the SYSTEM^%ZSTART entrypoint on non-mirrored environments and NotifyBecomePrimary^ZMIRROR (in %SYS) on mirrored ones.
Suggested code fragments:
%ZSTART ; Custom startup logic suitable for non-mirrored environments
; See https://docs.intersystems.com/irislatest/csp/docbook/DocBook.UI.Page.cls?KEY=GSTU_customize#GSTU_customize_startstop
q
;
SYSTEM ;This subroutine is called during system startup
; Start the Serenji Service
try {
j ServiceStart^%Serenji|"SERENJI"|
}
catch e {
d ##class(%SYS.System).WriteToConsoleLog("SYSTEM^%ZSTART error: "_e.AsSystemError(),,1)
}
q
or
ZMIRROR ; Custom logic for specific mirroring events
; See https://docs.intersystems.com/irislatest/csp/docbook/DocBook.UI.Page.cls?KEY=GHA_mirror#GHA_mirror_set_tunable_params_zmirror_routine
q
;
NotifyBecomePrimary() PUBLIC {
; This procedure is called as a notification when this system becomes Primary
; It does not return any value
; Start the Serenji Service on the primary system
try {
j ServiceStart^%Serenji|"SERENJI"|
}
catch e {
d ##class(%SYS.System).WriteToConsoleLog("NotifyBecomePrimary^ZMIRROR error: "_e.AsSystemError(),,1)
}
q
}
When you used the Command Picker to add a folder to your workspace, your workspace settings file was given an entry like this:
"folders": [
{
"uri": "serenji://tin.iris181/",
"name": "Serenji: tin.iris181"
}
],
By editing the workspace JSON directly you can change the display name of the root folder.
You can suffix a folder URI with a namespace name in order to constrain the folder to a single namespace. This happens automatically if you enter a namespace name when running the Serenji: Add Folder to Workspace command, in which case the name property is also suffixed with the namespace name.
You can also use the serenji-readonly scheme in a folder URI instead of the serenji scheme, resulting in readonly access to everything under that folder. In addition the serenji-readonly scheme doesn't filter out generated or mapped files (e.g. INTs generated from CLS and MAC files, or code mapped from another database).
Examples of these techniques are shown below:
"folders": [
{
"uri": "serenji://tin.iris181/SAMPLES",
"name": "Serenji: tin.iris181 SAMPLES"
},
{
"uri": "serenji-readonly://tin.iris181/SAMPLES",
"name": "Readonly view of SAMPLES on IRIS181 (generated or mapped code not filtered out)"
},
{
"uri": "serenji://tin.iris181/",
"name": "Serenji: tin.iris181"
}
],
Notice how you can amend the root name, and can dedicate a root to a single namespace if you want.
When debugging, communication with the Serenji Service is always done over a secure socket connection. When you installed Serenji on your InterSystems environment an SSL/TLS configuration entry named 'Serenji' was created, using a generic self-signed certificate file and unpassworded private key file that is bundled with the Serenji kit. This is done for convenience, since the arrangement is sufficient to enable VSCode to connect for debugging. However the use of a publicly-shared private key leaves the network trafic vulnerable to decryption by anyone in possession of that key. It also means the the VSCode client does not verify the identity of the server it connects to.
To protect debug network traffic against decryption by third parties, go to 'System Administration > Security > SSL/TLS Configurations' in Portal. Edit the 'Serenji' entry, changing the fields in the section titled "This server's credentials" so as to make it use your own certificate and private key.
To remove Serenji's components from an InterSystems server, deleting any information recorded by the embedded Deltanji, do the following:
Stop the Serenji Service process: do ServiceStop^%Serenji
Note what directory the embedded Deltanji was installed in. You can find this in the global node ^%Serenjvc("programFiles") in the SERENJI namespace:
SERENJI>write ^%Serenjvc("programFiles")
In Portal use System Administration > Configuration > Additional Settings > Source Control to reset to NONE the source control class of each namespace you previously put under the control of this Deltanji instance. The old setting for these namespaces will be SerenjiStudio.SourceControl or SerenjiStudio.SourceControl.Ensemble.
For each namespace you put under Deltanji's control, plus for the %SYS namespace, use System Administration > Configuration > System Configuration > Namespaces to review mappings defined on the %ALL pseudo-namespace for globals, rountes and packages. Remove all mappings directed to the SERENJI database. Remember to save the changes.
Use System Administration > Configuration > System Configuration > Local Databases to delete the SERENJI database. Review the confirmation page to make sure that your action will only affect the SERENJI namespace. If any other namespaces are listed here, stop and consult support@georgejames.com. Provided only the SERENJI namespace is listed on the delete dialog, check the box alongside it and also check the box to allow deletion of the database file. Click the "Finish" button to proceed with the deletion.
If local databases SERENJIENSTEMP and SERENJISECONDARY exist, delete these as well.
Use System Administration > Security > Roles to delete the %DB_SERENJI and SerenjiUser roles, plus the %DB_SERENJISECONDARY role if it exists.
Use System Administration > Security > Resources to delete the %DB_SERENJI resource, plus the %DB_SERENJISECONDARY resource if it exists.
Use System Administration > Security > Web Applications to delete the /serenji/deltanji application if it remains.
In each namespace Serenji's Deltanji was controlling, delete the ^Serenjvp global.
If you previously added code into the %ZSTART routine in the %SYS namespace to autostart the Serenji Service process, remove that code.
Verify that a restart of your InterSystems environment works correctly.
Delete the Serenji parent directory of the Deltanji installation directory that you identified in step #1.