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 extension integrates Deltanji as a VSCode source control provider which you can interact with from the Source Control viewlet. Click here 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.1.4.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 (hereafter 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 a version of this extension earlier than 3.1.3. If you already have the 3.1.3 server-side routines installed you are all set, because there is no 3.1.4 set of routines.

References to IRIS apply equally to Caché, Ensemble and HealthShare environments.

Proceed as follows:

  1. Download server-side components

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

  2. Unzip the file

    The zip contains a filetree rooted in a directory called Serenji.

  3. Move the unzipped 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 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

    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.

  5. Load the installer class

    This step will import and compile a class called Serenji.Installer containing 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.

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

  6. Run the installer

    This step will add the following to your InterSystems configuration if they do not already exist:

    Optionally, if you want the SERENJI database to be located somewhere other than in a subfolder of the mgr directory, do the following sub-step before proceeding:

    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. In particular, if you plan to connect VSCode to an existing Deltanji Team or Enterprise edition instance, opt not to start the service process; you will be using the existing Deltanji diff server (%vc830) instead.

    If you want to know more about the Serenji Service, click here.

  7. Review the results

    When the RunInstall method 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

  8. Tidy up

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

  9. Configure mirror failover member if applicable

    If your target environment is a failover member of an InterSystems mirroring configuration, add the SERENJI database to the mirror and configure 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.

You are now ready to configure your Visual Studio Code client for editing.

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, pick one.
  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, choose 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.

Debug a REST service

  1. Install the 'REST Client' extension (humao.rest-client) into VSCode.
  2. Create a .http or .rest file to orchestrate REST testing using that extension.
  3. Augment your launch URLs in that file, adding a magic query parameter {{serenji}}. For example:
GET http://localhost:57772/rest/coffeemakerapp/coffeemaker/1 HTTP/1.1 ?{{serenji}}
  1. Use the 'Debug with Serenji' button that appears above the URL.

Troubleshooting

The Serenji Service

The Serenji Service is an ObjectScript process (%Serenj830). Unless you will be connecting to an existing Deltanji Team or Enterprise edition instance, the Serenji Service 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. Provided you allowed that, skip this section and start setting up VSCode.

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):

Tips:

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.