Serenji - Getting Started

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.

Installation

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.5.vsix and use the "..." menubutton in upper right corner of the Extensions viewlet to choose "Install from VSIX..."

Configure your InterSystems server

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.

Install the Serenji software

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:

  1. Download the server-side components to your server from this link: https://georgejames.com/files/Serenji-3.0.5.zip

  2. Unzip it. The zip contains a filetree rooted in a directory called Serenji.

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

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

  5. 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 will import and compile a class called Serenji.Installer. This contains a classmethod (RunInstall) that you will subsequently run to make changes to your InterSystems configuration. The Serenji.Installer class can be loaded into any existing namespace. We suggest you use the USER namespace if it is available.

  1. 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")

The next step (RunInstall) will add the following to your InterSystems configuration if they do not already exist:

If you want the SERENJI database to be located somewhere other than in a subfolder of the mgr directory, use Portal to create the database before proceeding to the next step. Create only the database, not a matching namespace; leave that task to the next step of this procedure. Name the database SERENJI and create a dedicated security resource for it named %DB_SERENJI. No public privileges are required on the resource.

  1. Invoke the 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\")

The method prompts before starting the Serenji Service process. See the next section for more information about this service.

  1. When the RunInstall method completes, turn off terminal logging if you previously enabled it.

  2. Review the output for any error messages. If you are unsure whether the installation succeeded, contact support@georgejames.com

  3. Tidy up by deleting the Serenji.Installer class from the namespace you initially imported and ran it in, e.g.

USER>d $system.OBJ.Delete("Serenji.Installer.cls")

  1. If your target environment is a failover member of an InterSystems mirroring configuration, consider adding the SERENJI database to the mirror and configuring the namespace and other settings on the other failover member so that it can host your editing and debugging whenever it takes over as master.

The Serenji Service

The Serenji Service is an ObjectScript process (%Serenj830) that must be running before the Serenji extension can connect VSCode to that InterSystems environment.

The installation procedure above will have prompted for permission to start this service. If you need to start it 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):

Tips:

Configure your Visual Studio Code client for editing

Follow these steps to prepare your VSCode environment for editing code in your InterSystems server environment.

OPTIONAL - Add a User Setting to define a connection

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 VSCode workspace.

If you want to connect elsewhere, add a section of JSON to your VSCode User Settings. One way to access this is:

Below is an example of a connection definition for a 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" }, },

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.

Remember to save the modified settings.json file (Ctrl/⌘+S).

Create a VSCode workspace

A workspace specifies which server(s) you will work on, and in which namespace(s).

  1. Start with no workspace open (i.e. close any currently open one via 'File\Close Workspace' or Ctrl/⌘+K followed by F).
  2. Open the VSCode Command Palette, e.g. by typing F1 or Ctrl/⌘+Shift+P
  3. Run Serenji: Add Folder to Workspace
  4. Choose the localhost entry if appropriate, else the server you previously added to User Settings, e.g. tin.iris181
  5. If the server definition doesn't specify a namespace, optionally enter one when prompted. Or leave that field empty if you want the workspace to access all namespaces on the server.
  6. If the server definition doesn't include a username, enter one when prompted. The user account must hold the SerenjiUser role or the %All role on the target server.
  7. If prompted for your password (because you omitted it from User Settings), enter it.
  8. Save the workspace (File\Save Workspace As...), then close and reopen it. A quirk of VSCode means that unless you do this the set of workspace-specific settings received from the InterSystems environment will not be correctly activated.

If the connection fails, check that the Serenji Service is running on the target server, and verify that its ports are not blocked by any firewalls.

Explore and edit code

In 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, 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 VSCode. Compilation happens immediately after saving, and compilation errors appear in the Problems panel.

Web application files appear under the package associated with the web application (i.e. the package containing classes generated from CSP files). The default package is 'csp', but this can be overridden in the web application setup page of InterSystems Portal.

The tree does not show generated code (e.g. INTs generated from CLS or MAC definitions; classes generated from CSP files). Code that is not stored in the namespace's default database (mapped code) is also hidden.

Enable 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, routine or file, 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:

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, routine or web application file can be deleted from within VSCode. Be aware that this action will immediately and irreversibly delete the item from the namespace or associated web application file directory on your server.

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.

Configure your Visual Studio Code client for debugging

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.

Obtain a debug key

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

  2. Expand the workspace root, e.g 'Serenji: localhost'

  3. Expand the .serenji folder.

  4. Open the file named registrationData.txt (the contents are generated dynamically when opened).

  5. 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: MYWORKSTATION: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

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

  7. Follow the instructions in that email to download your keyfile and save it.

Tell VSCode where to find your keyfile

Add a license object property to the entry you previously defined in serenji.servers in your User Settings (JSON view). The license object should be given a keyfile string property. 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" } }, ... },

If you are using the built-in localhost connection your User Settings (JSON view) may not yet have a serenji.servers section at all. Add a minimal one as follows, altering 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 must be doubled in JSON string values.

Debugging

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.

Launch a routine for debugging

  1. In the Debug viewlet (Ctrl/⌘+Shift+D) use the configuration selector dropdown to choose a 'Routine' entry. Then click the adjacent green 'go' button.
  2. If prompted for a namespace, enter one e.g. USER (this can also be entered in lowercase).
  3. When prompted for an execution startpoint, enter a simple one for your initial testing, e.g. INT^%T
  4. The target code will load and execution will suspend at the startpoint you specified.
  5. Use VSCode's standard debug facilities.

Debug a classmethod

  1. In the Debug viewlet (Ctrl/⌘+Shift+D) use the configuration selector dropdown to choose a 'ClassMethod' entry. Then click the adjacent green 'go' button.
  2. If prompted for a namespace, enter one e.g. USER (this can also be entered in lowercase).
  3. When prompted for an execution startpoint, enter a string in the format Package.Class.ClassMethod() e.g. %Library.PopulateUtils.City(). This format is more concise than the conventional ##class format.
  4. The target code will load and execution will suspend at the startpoint you specified.
  5. Use VSCode's standard debug facilities.

Debug a running process

  1. In the Debug viewlet (Ctrl/⌘+Shift+D) use the configuration selector dropdown to choose an 'Existing Process' entry. Then click the adjacent green 'go' button.
  2. When prompted, enter the PID ($JOB number) of the process you want to debug.
  3. When that process executes its next command Serenji will attempt to start debugging it.
  4. Use VSCode's standard debug facilities.

Troubleshooting

Next Steps

You may wish to take some of the following extra steps.

Autostart the Serenji Service

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 }

Adjust your workspace configuration

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.

Connect a workspace to more than one target

Run Serenji: Add Folder to Workspace again, pick a server and optionally specify a namespace.

For example, you might 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.

Install your own server certificate

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.

Uninstalling

To remove Serenji's components from an InterSystems server, deleting any information recorded by the embedded Deltanji, do the following:

  1. Stop the Serenji Service process: do ServiceStop^%Serenji

  2. 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")

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

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

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

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

  7. If local databases SERENJIENSTEMP and SERENJISECONDARY exist, delete these as well.

  8. Use System Administration > Security > Roles to delete the %DB_SERENJI and SerenjiUser roles, plus the %DB_SERENJISECONDARY role if it exists.

  9. Use System Administration > Security > Resources to delete the %DB_SERENJI resource, plus the %DB_SERENJISECONDARY resource if it exists.

  10. Use System Administration > Security > Web Applications to delete the /serenji/deltanji application if it remains.

  11. In each namespace Serenji's Deltanji was controlling, delete the ^Serenjvp global.

  12. If you previously added code into the %ZSTART routine in the %SYS namespace to autostart the Serenji Service process, remove that code.

  13. Verify that a restart of your InterSystems environment works correctly.

  14. Delete the Serenji parent directory of the Deltanji installation directory that you identified in step #2.