Serenji - Getting Started

Overview of Serenji

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.

Download

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

Compatibility

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.

Deltanji

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.

Install server components

Follow the steps below to install the Serenji server components, this includes upgrading from an earlier version of Serenji.

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

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

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

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

  5. Run the installer

    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.

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

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

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

Configure VS Code for editing with Serenji

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.

Add a connection definition

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:

    "serenji.servers": {
        "tin.iris181": {
            "host": "tin.mydomain",
            "port": 43211,
            "username": "SuperUser",
            "password": "SYS",
            "license": {
                "keyfile": ""
            }
        },
    },

Please note:

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

Create a workspace

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

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

  2. In the Explorer view (Ctrl/⌘+Shift+E) click 'Open Serenji Folder'.

  3. Choose the localhost entry if appropriate, else the server you previously added to User Settings, e.g. tin.iris181

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

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

Explore and edit code

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.

Create a new class, routine or file

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.

Protect your server code

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.

Prepare to debug

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.

Request a debug key

  1. Switch to the 'Run and Debug' view (Ctrl/⌘+Shift+D).
  2. Click the 'Request Debug License' button.
  3. If prompted, choose the server.
  4. Follow the instructions on the dialog. Before sending the key request email that gets composed, verify that the connection used the username you want the debug license for.
  5. Once we have received your email, we will generate a keyfile and send it to you with installation instructions.

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.

Tell VS Code where to find your keyfile

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.

Debug or run your code

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.

Using F5

  1. Press F5 to debug or Ctrl/⌘+F5 to run.

The closer your cursor is to the code you want to execute, the fewer prompts you will need to respond to.

'Run and Debug' view

  1. Switch to the 'Run and Debug' view (Ctrl/⌘+Shift+D).
  2. Use the command buttons which Serenji contributes there. Ignore VS Code's built-in 'Run and Debug' button at the top of the pane, and also the text links near it. Serenji is optimized for configurationless debugging and behaves best without a launch.json file.

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.

Code lenses

  1. Open the class or routine you want to debug or run.
  2. Click the 'Debug' or 'Run' code lens above a runnable code block:

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.

Debug a running process

  1. In 'Run and Debug' view (Ctrl/⌘+Shift+D) use the 'Debug Running Process' button. Alternatively, open the Command Palette (F1 or Ctrl/⌘+Shift+P) and choose Serenji: Debug Running Process...
  2. If prompted, choose the target server.
  3. Choose the process you want to debug. The list includes information about each process, allowing you to filter by typing.
  4. When that process executes its next command Serenji will attempt to attach and start debugging it.

Debug a REST service

  1. Install the 'REST Client' extension (humao.rest-client) from the 'Extensions' view (Ctrl/⌘+Shift+X).

  2. Following the REST Client instructions, create a .http or .rest file to orchestrate REST testing.

  3. 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}}
  1. Use the 'Debug with Serenji' button that appears above the URL.

Troubleshooting

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

The Serenji Service

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

Enhance your environment

Once you have installed Serenji, you may want to configure the following settings to your working environment.

Autostart the Serenji Service

You can add code to your InterSystems environment to enable this:

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
}

Tune your workspace configuration

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.

Connect a workspace to more than one target

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.

Always switch to the Debug Console

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.

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

Uninstall Serenji

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 or ZMIRROR 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.

Footnotes

How the Serenji server installer affects your server configuration

When you run the installer the following will be added to your InterSystems configuration:

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: