· Jan 30, 2023

The new $system.external interface

The new $system.external interface (aka "InterSystems External Servers") is used to call/integrate with external language code/libraries, it replace the old gateways (for example Java gateway) that required the import of proxy objects.

Note that the documentation for the old gateways has been removed from IRIS, so only the new $system.external interface is somewhat (i.e. insufficiently) documented.

Regarding the migration from old gateway to new  $system.external interface the documentation says:

External servers use an enhanced and simplified form of the older Dynamic Object Gateway technology. All Object Gateway features are still available, so upgrading your code is a simple matter of replacing certain class and method references.

Unfortunately that's definitely not the case, apart from very basic code/interface a rewrite of both sides of the interface code (Java and IRIS) is necessary to make it work.

In addition, the promise during the last few years of ISC events (Global Summits) was that you can take advantage of a wide variety of external libraries and consume them directly from IRIS, unfortunately, to do so, more often than not you need to "wrap" the libraries to allow calling them from IRIS.

So, what is reported in the documentation is what the implementation should have been and is not or is just a "bug" in the documentation that is overoptimistic?

What do you think?

If any InterSystems representative is listening, what's your opinion about it?


Discussion (14)5
Log in or sign up to continue

The idea is simple and I'm not sure it can be considered "documentation improvement" or it make sense in the "open exchange".

The idea is: add all the missing documentation for $system.external!!

The problem in not poor documentation, the problem is the MISSING DOCUMENTATION.

And in case you wonder, yes, I have reported this to WRC and sent a feedback to the ISC documentation team.

Nothing has happened.

On the same topic:

Using arrays in $system.external .NET gateway


Hi Enrico,

I am listening! $system.external does not replace the old Java Gateway but the old Java and JDBC Gateways should still be available. I am not intimately familiar with either of those although I did some of the refactoring work with them both. I am not aware of any user code changes that are necessary to keep using them.

If you want to use the new External Java Server then you will necessarily need to write new code. I am happy to provide demos showing how this can be done. I can also assist you with implementing your own project to get you started. Just let me know how you wish to proceed.

As for leveraging existing Java libraries, you should be able to do many things without writing new Java code but not everything. If you have some examples of libraries you have attempted to use but were not successful, please provide information so that I can attempt to replicate your issues.

As always, I am here, listening, and happy to help!!


Hi Dan! I'm please you are listening 😊

"I am listening! $system.external does not replace the old Java Gateway but the old Java and JDBC Gateways should still be available."

I know it's "still there" and works, however all the documentation for the old Java and .NET Gateway has been removed since long time (starting from IRIS?), so implementing it today it's difficult for any developer without previous experience.
In addition, I'm not sure if it would be a good idea to implement today external calls using the old Gateway, I assume that using the new $system.external is preferred.
In fact the documentation contains some info for converting from old gateway to new $system.external:

"...upgrading your code is a simple matter of replacing certain class and method references..."

Assuming that upgrading is "simple matter of replacing certain class and method references", unfortunately for MANY use cases there is no documentation of what to replace with what.

The problem is that now we have no documentation of the (still available) old gateway and "scarce" documentation for the new one.
I don't remember the details of the old gateway documentation, however it offered two GREAT code samples where most (if not all) the functionality was implemented:


Using only documented feature/methods of $system.external is not possible to convert the old samples to use $system.external.

So, my idea was to encourage the implementation of two samples (maybe Phyton as well?) with all the features.

That's the issue at hand.



For some reason I didn't get an email alert that you had replied. I'm sure it is buried in my "group" mail somehwere - that's my fault and I'll try to get that sorted.

%Net.Remote.DotNet.Test - I can't help much with that but I certainly can with %Net.Remote.Java.Test. I'll take a look at that now.

$system.external.* is just a helper to get a gateway connection to an external language server such as the Java Server. I refer to the "gateway" as the connection. Maybe that doesn't work for every one. Sorry :(

Once you have a gateway connection you can interact with the external Server using methods supported by that connection. Some of those methods are still unknown to me so I'll have to do some research.

Stay tuned!


Along with a co-worker, I worked on this for three days. The good news is that I have something to show. The not-so-good news is that we discovered a bug and a deficiency. The better news is that the next version of JDBC to be released will include these fixes and enhancements. Also good news is that most of the old %Net.Remote.Java.Test class works with minor refactoring.

Mo Cheng will be adding information on how to leverage a more backward compatible Java Gateway. The legacy Java Gateway used generated classes and the new Dynamic Gateway ($system.external) does not. I'll leave that description for Mo to provide.

For now - pending review - I am ready to share a new class (actually a full project). I am just waiting for a place for this to be posted. In the meantime, I could post code snips here. Let me know.

We posted a sample project to the community github account. There are java and dotnet versions of the project. Take a look and we would appreciate any feedback you may want to offer.



Please note that there are some deficiencies when working with parameterized Java types when using the new External Java Server. Some of these were discovered during the refactoring of the %Net.Remote.Java.Test code. Some have already been addressed but not yet included in a release.