WebSphere Server Tools

Run, debug, build and hot-publish to a local IBM WebSphere Application Server (traditional) or WebSphere Portal — from VS Code.

Rational Software Architect and WebSphere Developer Tools are official IBM tools, but if you want to use VS Code, you can use WebSphere Server Tools. It transfers your daily workflow to VS Code: start and stop the server, connect the debugger, compile Maven modules one by one, and copy the result to the running server in seconds, without needing to reinstall the application.

Unofficial community project. It is not affiliated with, endorsed or supported by IBM. IBM and WebSphere are trademarks of International Business Machines Corp.

Contents

• Highlights
• Quick start
• The panel
• Everyday workflows
• Maven
• Hot publish: how it works
• Configuration
• Commands
• Security
• Troubleshooting
• Requirements
• Development
• Roadmap

Highlights

Quick start

1. Install the extension and open the folder of your Java project (any folder with a pom.xml).
2. Open the WebSphere view in the Activity Bar.
3. Run WebSphere: Detect Environment (if more than one profile or server is found you will be asked which one).
4. Run WebSphere: Detect Installed Applications. It matches what is installed in installedApps with the Maven projects of your workspace and saves the result in .vscode/settings.json.
5. If administrative security is on, run WebSphere: Configure User and Password.
6. Press ▶ to start the server, then 🐞 to attach the debugger.

Run WebSphere: Show Resolved Environment at any time to see every value in use and whether it was auto-detected or configured.

The panel

WEBSPHERE
├─ SERVER
│  ├─ ● WebSphere_Portal   running · debug 7777        [🐞] [⟳] [■]
│  ├─ Applications
│  │  ├─ 🌐 MyPortalWeb      war · my-web               [⟳]
│  │  │   ├─ Publish web resources (xhtml, js, css…)
│  │  │   ├─ Build & publish classes
│  │  │   ├─ Build & publish all 9 modules
│  │  │   ├─ Modules (9)  ▸ my-core   WEB-INF/lib/my-core-1.0.jar   [⬆]
│  │  │   ├─ Map shared libraries (MyProperties, LOG4J)
│  │  │   └─ Restart application
│  │  └─ 📦 MyEJBApp         ear
│  ├─ Logs           follow SystemOut · errors since startup · open log
│  ├─ Tools          app status · backup · trace · certificates · debug mode · console
│  └─ Configuration  user/password · detect · resolved environment · settings
└─ MAVEN PROJECTS
   └─ 📚 my-parent (pom)
      ├─ 🌐 my-web (war)                [clean install] [▶ goals…]
      ├─ 📦 my-core (jar)
      └─ 📦 my-ejb (ejb)

The status bar shows ● WebSphere_Portal running · 🐞 7777. Click it to open the panel.

Everyday workflows

Maven

The Maven Projects view shows each aggregator with its modules, including modules that live outside the workspace folder (<module>../../other-repo/lib</module>).

You can run goals from:

• the inline buttons of a project (clean install, Run Goals…);
• the Maven (WebSphere) submenu of the view, the Explorer (right-click a folder or pom.xml) and the editor title of a pom.xml;
• the Command Palette (WebSphere: Maven: …), which uses the project of the active editor.

Run Goals… accepts any goals and flags (for example clean install -U -Pdev) and remembers your last runs.

Each run uses:

• JDK: wasTools.maven.javaHome, or by default the JDK bundled with WAS (<wasHome>/java/<version>), so the classes always match the server's Java.
• Maven: wasTools.maven.executable, or maven.executable.path, mvnw, MAVEN_HOME and PATH, in that order.
• Flags: -o when wasTools.maven.offline is on, -DskipTests unless the goals include test, plus wasTools.maven.extraArgs.

Hot publish: how it works

WebSphere runs applications from an exploded copy under <profile>/installedApps/<cell>/<app>.ear/. Hot publish copies the changed files there, which is the same thing Eclipse-based tools do when they publish to a local server.

workspace                                    <profile>/installedApps/<cell>/MyApp.ear/
my-web/WebContent/**          ──copy──▶      MyWeb.war/**                (web resources)
my-web/target/classes/**      ──copy──▶      MyWeb.war/WEB-INF/classes/**
my-core/target/my-core.jar    ──copy──▶      MyWeb.war/WEB-INF/lib/my-core-1.0.jar
my-ejb/target/my-ejb.jar      ──copy──▶      MyEJB.jar   |   lib/…        (EAR modules)
                                   │
                                   └── previous file saved first in <backupDir>/publish_<app>_<what>_<timestamp>/

Safeguards:

• Only changed files are copied (byte comparison).
• Backups: every overwritten file is saved first, so any publish can be undone by copying the backup back.
• Descriptors (web.xml, portlet.xml, faces-config*.xml) are never copied, only reported. ibm-*-bnd/ext files, which WAS rewrites at install time, are ignored.
• Bytecode check: a publish is refused if a class targets a newer Java than the server runs (class version above wasTools.publish.maxClassVersion, auto-detected from the server JDK). This catches a frequent problem: the Java language server compiling target/classes with its own newer JDK.

Configuration

Every value is resolved in three layers: explicit setting → auto-detection → generic default. Leave a setting empty (or 0) to auto-detect it.

Put team values in the workspace .vscode/settings.json and commit it. Put personal values in your user settings.

Server

Ports (0 = auto from serverindex.xml / server.xml)

wasTools.ports.https (WC_defaulthost_secure), wasTools.ports.http (WC_defaulthost), wasTools.ports.adminHttps (WC_adminhost_secure), wasTools.ports.soap (SOAP_CONNECTOR_ADDRESS), wasTools.ports.debug (JDWP).

Maven

wasTools.maven.executable, wasTools.maven.javaHome, wasTools.maven.offline (false), wasTools.maven.skipTests (true), wasTools.maven.extraArgs ([]), wasTools.maven.goals (goals offered by Run Goals…).

Applications

"wasTools.applications": [
  {
    "name": "MyPortalWeb",                    // application name in WAS
    "type": "war",                            // war: web root + WEB-INF/classes + modules
    "installedPath": "C:\\IBM\\WebSphere\\wp_profile\\installedApps\\Cell01\\MyPortalWeb.ear\\MyWeb.war",
    "webProject": "my-web",                   // Maven project folder, relative to the workspace
    "webRoot": "WebContent",                  // optional: WebContent or src/main/webapp by default
    "sharedLibraries": ["MyProperties", "LOG4J"],
    "modules": [
      { "project": "my-core", "target": "WEB-INF/lib/my-core-1.0.jar" }
    ]
  },
  {
    "name": "MyEJBApp",
    "type": "ear",                            // ear: module jars only
    "installedPath": "C:\\IBM\\WebSphere\\wp_profile\\installedApps\\Cell01\\MyEJBApp.ear",
    "sharedLibraries": ["MyEJBProperties"],
    "modules": [
      { "project": "my-ejb",      "target": "MyEJB.jar" },
      { "project": "my-services", "target": "lib/my-services.jar" },
      { "project": "C:\\work\\other-repo\\common", "target": "lib/common.jar" }
    ]
  }
]

Detect Installed Applications builds this list for you:

• Web project: a project is linked to an installed war only if at least half of a sample of its web files exist in the war.
• Modules: a jar is linked to a Maven project when its name, without the version, matches the project's artifactId or folder name.
• Shared libraries: read from the application's deployment.xml.

Publishing, backups and logs

Commands

All commands are in the Command Palette under WebSphere:.

Security

• Password storage: the administrator password is stored with the VS Code SecretStorage API (Windows Credential Manager, macOS Keychain, libsecret), one entry per profile and user. It is never written to settings or files.
• Passing it to WAS tools: stopServer, wsadmin and xmlaccess receive it as the environment variable WAS_PASSWORD, expanded by cmd/sh at run time. The command line shown in the terminal reads -password %WAS_PASSWORD%, and any echo of the value is masked as ****.
• Confirmations: anything that changes the WAS configuration asks first in a modal dialog: debug mode, trusting a certificate, shared libraries, restarts. Trusting a certificate backs up trust.p12 first.
• Untrusted workspaces: the extension is disabled in them, because it runs Maven and WAS command line tools.
• SOAP traces: they include full messages, credentials too. The extension reminds you to turn the trace off and delete trace.log.

Troubleshooting

Still stuck? Run Show Resolved Environment and include its output when you open an issue.

Requirements

• A local profile of WebSphere Application Server traditional 8.5.5 / 9.0 or WebSphere Portal 8.5 / 9.x, on Windows or Linux.
• Maven 3.x.
• Debugger for Java to attach. The extension offers to install it.
• Recommended: Extension Pack for Java, with java.configuration.runtimes set to the server's Java version.

Not supported (yet): remote servers, Network Deployment cells (deployment manager / node agents), WebSphere Liberty (use Liberty Tools).

Development

git clone https://github.com/davidmonterocrespo24/vscode-websphere-server-tools.git
cd vscode-websphere-server-tools
npm install
npm run compile        # generates the manifest/translations and compiles TypeScript

Press F5 to open an Extension Development Host. To open a test workspace directly, add its path to args in .vscode/launch.json.

Package a .vsix with npm run package, then install it with code --install-extension websphere-server-tools-<version>.vsix.

Translations: add a package.nls.<lang>.json (generated by scripts/gen-manifest.js) and an l10n/bundle.l10n.<lang>.json.

Roadmap

• Getting-started walkthrough.
• Full application update (war/ear) through wsadmin, and Portal web module update through XMLAccess.
• Problem matcher for Maven compiler errors.
• Several servers or profiles in one workspace.
• macOS testing.

License

MIT © David Montero