Create and Manage Connection Profiles for Your InterSystems Servers

Prerequisites for Your InterSystems Server

The ObjectScript extension pack communicates with an InterSystems server instance using the instance’s /api/atelier web application.

Therefore, to connect to an instance from VS Code, you must ensure that the /api/atelier web application is configured as follows:

• Your web server and Web Gateway must be configured to route requestsOpens in a new tab for the instance’s /api/atelier URL endpoint (or for a parent path containing that endpoint) to the instance.

  The InterSystems IRIS installer’s automatic web server configuration procedure configures the web server and Web Gateway to serve all requests for the prefix path /<instanceName> to the instance; this is sufficient, provided that you configure the path prefix for the server’s connection profile accordingly.

• The InterSystems server’s /api/atelier web application must be:

  • enabled.

  • configured to use the same authentication method which you have configured other web applications (such as the Management Portal) to use.

  Refer to Create and Edit ApplicationsOpens in a new tab for guidance modifying InterSystems IRIS web applications.

Add a New Server Connection Profile

To add a new connection information profile for an InterSystems IRIS server, select the plus sign (+) in the title bar of the InterSystems Servers view.

When prompted, provide the following values:

• Name of new server definition — an arbitrary name to identify this server.

• Description (optional) — a brief description of the server.

• Hostname or IP address of web server — the host name or IP address of the web server that publishes the web services for your target InterSystems server through the InterSystems Web GatewayOpens in a new tab.

• Port of web server — the port number at which your web server hosts your target InterSystems server.

• Path prefix of instance (optional) — if you are connecting to your target InterSystems server using a web server that hosts multiple InterSystems servers, this is the URL path which precedes the application path and identifies the target serverOpens in a new tab. For example, a server named irisprod may make its web applications available at https://samplehost.com:8080/irisprod/. In this example, the path prefix would be "/irisprod".

• Username (optional) — the username VS Code should use when it authenticates to this server. If a username is not provided, the InterSystems Server Manager authentication provider prompts you to provide one each time you connect to the server.

• Confirm connection type — the protocol used for connections. Possible values are http and https.

  Note:

  Additional configuration may be necessary if you want to establish an HTTPS connection using a self-signed certificate.

Once you have entered these values, the extension stores the server definition in your user-level settings.json file. Within the InterSystems Servers view, the new server appears at the top of the Recent folder and in the All Servers folder.

You can edit a server connection profile at any time; see Editing a Server Configuration for instructions.

Import Connection Profiles from the Windows Registry

The InterSystems Server Manager can create connection profiles for all the servers that you previously defined with the original Windows application of the same name. If you are migrating from InterSystems Studio, this means you do not have to redefine your connection profiles manually.

To import existing server connection profiles from the Windows Registry, select Import Servers from Windows Registry from the ... (ellipsis) menu in the title bar of the InterSystems Servers view, as illustrated in the following image:

Alternatively, you can invoke this command by selecting the InterSystems Server Manager: Import Servers from Windows Registry menu option from the command palette.

Edit a Connection Profile

If you need to modify a server connection profile in the user-level settings.json file, perform the following steps:

1. Select File > Preferences > Settings (Code > Preferences > Settings on Mac) from the menu.

2. Select the User settings level.

3. Select Extensions from the outline section of the Settings editor pane.

4. Select InterSystems Server Manager from the list to find the InterSystems Server Manager section of the Settings editor, as illustrated in the following screen shot:

   

5. Select Edit in settings.json.

Alternatively, you can access the user-level settings.json file directly from the InterSystems view container’s Servers view: select the ... (ellipsis) button in the title bar of the Servers view, and then select Edit Settings.

A server connection profile in the settings.json file has the following structure, populated with the values which you provided when you configured the server:

{
    "intersystems.servers": {
        "iris-1": {
            "webServer": {
                "scheme": "http",
                "host": "localhost",
                "port": 443
            },
            "username": "_SYSTEM"
        }
    }
}

The components of this server connection profile are as follows:

• "iris-1" — the arbitrary name to identify the InterSystems IRIS server.

• "webServer" — the collection of properties which define the web server you use to connect to the InterSystems IRIS server through the InterSystems Web GatewayOpens in a new tab.

  • "scheme" — the protocol used for connections ("http" or "https").

    Note:

    Additional configuration may be necessary if you want to establish an HTTPS connection using a self-signed certificate.

  • "host" — the host name or IP address for the web server.

  • "port" — the port number for the web server.

  • "pathPrefix" — where applicable, the directory path under which the web server publishes the target InterSystems IRIS server’s web services.

• "username" — the username VS Code uses to authenticate to the server.

• "password" — password for the specified username.

  Important:

  Although supported, storing passwords as plaintext within the user-level settings.json file is not secure. For security reasons, InterSystems recommends using InterSystems Server Credentials to manage passwords. InterSystems Server Credentials securely stores and retrieves passwords from the workstation’s operating system keychain.