Serenji, from George James Software, provides an environment to edit and debug in a simple and straight-foward way so users can focus on producing high quality code.
Below is a short guide to get you started with Serenji. If you have any queries or problems during the installation process, please get in contact with us at support@georgejames.com.
You can download Serenji from the VS Code marketplace, or directly from the Extensions view (Ctrl/⌘+Shift+X) in VS Code. Search for Serenji and click install.
Alternatively, download a VSIX file from: https://georgejames.com/files/vscode-serenji-3.2.3.vsix. Use the "..." menubutton in upper right corner of the Extensions viewlet to choose "Install from VSIX...".
You will also need to download the Serenji server components from: https://georgejames.com/files/Serenji-3.2.3.zip
Serenji v3.2.3 is compatible with the following InterSystems environments:
You will need to be using version 2009.1 or later for editing and 2010.2 or later for debugging. If you use an earlier version please get in contact with us at support@georgejames.com.
Your download of Serenji includes a free Solo license of Deltanji, our version control tool, which you can access from the Source Control view or its web browser interface. For more information about Deltanji click here.
If your InterSystems environments already have Deltanji installed (previously called VC/m) please contact support@georgejames.com for advice about integrating Serenji with it.
Follow the steps below to install the Serenji server components, this includes upgrading from an earlier version of Serenji.
Download server components
If you haven't already done so, download the server components from https://georgejames.com/files/Serenji-3.2.3.zip and save the file on your server.
Unpack the server components
Unzip the server components - it contains a filetree rooted in the Serenji directory.
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 do not recommend saving it under C:\Program Files\ as that location may cause permission issues during the installation.
Log in on your InterSystems environment
Open a Terminal session in your InterSystems environment, authenticating as a user holding the %All role, such as SuperUser.
This level of permission is necessary so that the install script can add a namespace, database and web application to your InterSystems environment configuration.
Load the installer class
To make changes to your InterSystems configuration you will need to import and compile a class called Serenji.Installer containing a classmethod (RunInstall). We suggest you load it into the USER namespace, but you can use any existing namespace.
Switch to the USER namespace then 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")
For more information on what the installer will add to your InterSystems configuration, click here.
Invoke the RunInstall method of the class you loaded, passing as a parameter the path to the root of your Serenji kit, e.g.
USER>d ##class(Serenji.Installer).RunInstall("C:\Serenji\")
The method prompts before starting the Serenji Service process. Accept the default options unless you need to override them.
If you plan to connect VS Code to an existing Deltanji Team or Enterprise edition, do not start the service process as you will be using the existing Deltanji File Service instead.
Server installation complete
When the RunInstall method completes the server components are successfully installed. However if you’re unsure, check the output for any error messages.
If you have any problems please contact us at support@georgejames.com.
Tidy up
Delete the Serenji.Installer class from the namespace you initially imported and ran it in, e.g.
USER>d $system.OBJ.Delete("Serenji.Installer.cls")
Configure mirror failover member, if applicable
If your target environment is a failover member of an InterSystems mirroring configuration you'll need to add the SERENJI database to the mirror and configure the namespace and other settings on the other failover member.
This enables it to host your editing and debugging whenever it takes over as master.
Next, you will need to configure VS Code for the Serenji editor.
Follow the steps below to configure your VS Code client for exploring and editing code in your InterSystems server environment. The steps to configure VS Code to debug are in the next stage.
Serenji has an embedded connection definition named localhost which points to the default Serenji Service port (43211) on the local workstation (127.0.0.1).
If you have configured a local InterSystems server to run the Serenji Service on that port you may skip the rest of this section and proceed to create a Serenji workspace.
If you want to connect elsewhere, add a section of JSON to your VS Code User Settings. To do this:
Open the VS Code Command Palette (F1 or Ctrl/⌘+Shift+P)
Find the command Preferences: Open Settings (JSON) and pick it
Command Palette contents can be filtered by typing characters that appear in the command name, for example json.
Highlight and copy the below connection definition using Ctrl/⌘+C. This connection definition is an example for an InterSystems environment on host 'tin.mydomain' running the Serenji Service on port 43211:
"serenji.servers": {
"tin.iris181": {
"host": "tin.mydomain",
"port": 43211,
"username": "SuperUser",
"password": "SYS",
"license": {
"keyfile": ""
}
},
},
Please note:
In the above example the connection name is 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 (the 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.
If the username element is omitted or set to "" you will be prompted to enter one upon first connection to the target in each VS Code session.
The user account must hold the SerenjiUser role or the %All role.
Omit the password element if you don't want to store it in plaintext in your VS Code Settings file. You will then be prompted for your password the first time it is needed in a VS Code session.
The license element and its keyfile sub-element are placeholders showing you where to add a debugging keyfile path which you'll need in order to use Serenji's debugging features. We explain how to request a debug key in a later section.
Remember to save the modified settings.json file (Ctrl/⌘+S).
A Serenji folder specifies which server(s) you will work on, and in which namespace(s).
Close any other open workspaces (via 'File\Close Workspace' or Ctrl/⌘+K followed by F).
This will only need to be done when creating a new workspace consisting of a single Serenji folder. Once a workspace definition has been saved, next time that workspace is opened any already-open workspace will close automatically.
In the Explorer view (Ctrl/⌘+Shift+E) click 'Open Serenji Folder'.
Choose the localhost entry if appropriate, else the server you previously added to User Settings, e.g. tin.iris181
If the server definition doesn't specify a namespace, either enter one when prompted or leave that field empty in order to access all namespaces on the server.
If the server definition doesn't include a username or password, enter these when prompted. The user account must hold the SerenjiUser role or the %All role on the target server.
If the connection fails, check that the Serenji Service is running in the target InterSystems environment, and if the environment isn't on your local workstation verify that the service ports are not blocked by any firewalls. If you're still having problems contact us at support@georgejames.com.
In the VS Code Explorer view (Ctrl/⌘+Shift+E) expand the workspace tree and, if you allowed access to all namespaces on the server, expand one of the listed namespaces. Here you will find routines, classes and web application files that you can open.
Any changes you make to them here will be written to the namespace as soon as you save them within VS Code. Compilation happens immediately after saving, and compilation errors appear in the Problems panel.
The tree does not show generated code (INTs generated from CLS or MAC definitions and classes generated from CSP files), or mapped code that is not stored in the namespace's default database.
Enable VS Code breadcrumbs via the View menu so you can easily jump to methods, properties and line labels in your code. The Outline section of VS Code 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, routine or file, right-click at the appropriate place in the tree, then choose 'New File'.
Enter the required name, which must include the appropriate suffix:
The initial content of a new file comes from one of the template files that are located in the .serenji subfolder of your workspace root. You can edit these files. You can also create copies of them 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. These can be accessed using Ctrl/⌘+space, then typing method or property. After selecting a snippet, use the Tab key to move between fields within it.
A class, routine or web application file can be easily and accidentally deleted within VS Code. This will delete the item from the namespace or associated web application file directory on your server, making it no longer available. This action is irreversible, so please be careful when you are working.
We have included our version control tool, Deltanji alongside the Serenji extension to mitigate losing any work. To protect your server code by registering for code management, launch the Deltanji UI from the Command Palette (F1 or Ctrl/⌘+Shift+P) using Serenji: Open Deltanji in Web Browser. Find out more about how to use Deltanji here.
In order to debug or run code with Serenji you will need to request a debug key from George James Software. Without one you will only be able to write and edit code.
Each key enables debugging for a named user on a specific InterSystems environment. They are only issued for identifiable individuals, not for generic usernames such as 'Admin' or 'SuperUser'.
You will have needed to purchase a license for Serenji in order to receive a debug key which doesn't expire. A member of our team will let you know if you haven’t yet purchased one when you send a key request to us.
Keyfiles are generated during UK business hours. We endeavour to generate them as soon as we receive a request, however there may occasionally be delays in our response.
Once you have saved your keyfile you will need to add the file path to the 'serenji.servers' section you previously edited in the settings.json file. Open that file with the Preferences: Open Settings (JSON) command in Command Palette. It should look like this:
"serenji.servers": {
"tin.iris181": {
"host": "127.0.0.1",
"port": 43211,
"username": "me",
"license": {
"keyfile": "C:\\Users\\me\\Documents\\SerenjiKeys\\me-TIN-IRIS181.p12"
}
},
...
},
If you are using the built-in localhost connection your settings.json file might not yet have a serenji.servers section. In this case, add the following text immediately after the { character at the start of the file. Alter the keyfile value appropriately:
"serenji.servers": {
"localhost": {
"host": "127.0.0.1",
"license": {
"keyfile": "C:\\Users\\me\\Documents\\SerenjiKeys\\me-localhost.p12"
}
}
},
Note how backslashes in a Windows path must be doubled in JSON string values.
Serenji provides several ways to start debugging ObjectScript code:
Many of these ways also let you run the code without stopping at breakpoints or errors.
Serenji uses the native InterSystems debug facilities, which require INT code to be available. When you edit and save a class or a MAC routine with Serenji the post-save compile retains the generated INT code. 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. Alternatively, set that flag as a default for your namespace by running the following command there:
Do $System.OBJ.SetFlags("k")Then recompile your classes or MAC routines.
The closer your cursor is to the code you want to execute, the fewer prompts you will need to respond to.
If the buttons and instructions do not appear, check that no folder in your workspace defines any debug configurations in a .vscode/launch.json file, and that no configurations are defined in your workspace file.
For performance reasons Serenji does not suppress code lenses on private classmethods or procedures. However the InterSystems debugger cannot invoke these directly. If you need to debug them add a public helper classmethod / procedure to start debugging from.
Serenji: Debug Running Process...Install the 'REST Client' extension (humao.rest-client) from the 'Extensions' view (Ctrl/⌘+Shift+X).
Following the REST Client instructions, create a .http or .rest file to orchestrate REST testing.
Augment your launch URLs in that file, adding a query parameter {{serenji}}. For example:
GET http://localhost:57772/rest/coffeemakerapp/coffeemaker/1 HTTP/1.1
?{{serenji}}
Below are solutions to problems that can sometimes occur during the installation of Serenji. If your problem isn't resolved following these steps, or not listed below, please contact us at support@georgejames.com
During server installation, if you aren't able to fetch the zipfile from the George James Software website you can find an alternative copy in the targets subdirectory of the directory where the Serenji extension was installed by VS Code.
A Windows user named me would typically find it in: C:\Users\me\.vscode\extensions\georgejames.vscode-serenji-x.y.z\targets\
For Linux and macOS users it will typically be in: ~/.vscode/extensions/georgejames.vscode-serenji-x.y.z/targets/
VS Code must be able to connect to the TCP/IP ports the Serenji Service listens on. By default these are 43211 and 43212. If your target InterSystems environment is not located on your local workstation, make sure no firewalls between you and the target are blocking those service ports for incoming connections.
If your InterSystems environment target is running in a Docker container you must publish the Serenji Service ports to the same ports on the Docker host, for example by adding --publish 43211-43212:43211-43212 to your docker run command.
The Serenji Service is an ObjectScript process (%Serenj830). It must be running before Serenji can connect VS Code to the InterSystems environment, unless you are connecting to an existing Deltanji Team or Enterprise edition.
During the installation of Serenji you will have been prompted for permission to start this service. If you granted permission you can skip this step.
If you need to start the Serenji Service manually:
USER>zn "serenji"
SERENJI>d Service^%Serenji
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).
If you intend to use Serenji's debug features then the $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.
The service process usually appears in your system status display as the routine %Serenj830.
If you would like to start the Serenji Service silently, with no user interaction required, on the previously-chosen ports: DO ServiceStart^%Serenji or JOB ServiceStart^%Serenji.
The next section covers how to autostart the Serenji Service whenever an environment starts.
To stop the service: DO ServiceStop^%Serenji and to test whether it is running: WRITE $$ServiceStatus^%Serenji
Once you have installed Serenji, you may want to configure the following settings to your working environment.
You can add code to your InterSystems environment to enable this:
SYSTEM^%ZSTART entrypointNotifyBecomePrimary^ZMIRROR entrypopint (the ZMIRROR routine must reside in the %SYS namespace)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 initially created a Serenji workspace its JSON settings file got an entry like this:
"folders": [
{
"uri": "serenji://tin.iris181/",
"name": "Serenji: tin.iris181"
}
],
The Preferences: Open Workspace Settings (JSON) command in Command Palette quickly gets you to the correct file.
By editing the JSON you can change the display name of the root folder.
You can suffix a folder URI with a namespace name in order to constrain it to a single namespace. Suffixing 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 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 customize the root name, and can dedicate a root to a single namespace.
Run Serenji: Add Folder to Workspace again, pick a server and specify a namespace if desired.
This could be useful if you want to connect a workspace to your development server and to your test server, or create a workspace that accesses a subset of all the namespaces available on a server.
By default VS Code only switches to display the Debug Console when you debug for the first time after startup. If you want this switching to happen every time, set "debug.internalConsoleOptions": "openOnSessionStart". This is particularly useful if you are using Deltanji, which switches to the Output view to display its messages.
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 VS Code to connect for debugging. However the use of a publicly-shared private key leaves the network traffic vulnerable to decryption by anyone in possession of that key. It also means the VS Code client does not verify the identity of the server it connects to.
To protect debug network traffic against decryption by third parties:
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.
Use System Administration > Configuration > System Configuration > Namespaces to review mappings defined on the %ALL pseudo-namespace for globals, routines and packages. Delete any mappings directed to the SERENJI database. Remember to save each change.
Review mappings defined on the %SYS namespace for globals, routines and packages. Delete any mappings directed to the SERENJI database. Remember to save each change.
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 or ZMIRROR 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 #2.
When you run the installer the following will be added to your InterSystems configuration:
Security resource %DB_SERENJI.
Security role SerenjiUser with RW permission on %DB_SERENJI and U permission on %System_Callout.
Database SERENJI in a new SERENJI subfolder of the mgr directory of the InterSystems installation.
Namespace SERENJI using the SERENJI database for routines and globals, including explicit mappings placing the %Serenj* routines and globals there.
A default /csp/serenji web application for the SERENJI namespace.
Web application /serenji/deltanji that uses the SERENJI namespace and serves files from the Deltanji subfolder of the directory created in step #3 above.
SSL/TLS configuration Serenji.
If you want the SERENJI database to be located somewhere other than in a subfolder of the mgr directory, you will need to do the following before running the installer:
Use Portal to create the SERENJI database in a directory of your choice. Create only the database, not a matching namespace; leave that task to the installer.
Name the database SERENJI and create a dedicated security resource for it named %DB_SERENJI. No public privileges are required on the resource.