Skip to main content


The Production EXtension (PEX) framework provides you with a choice of implementation languages when you are developing interoperability productions. Interoperability productions enable you to integrate systems with different message formats and communication protocols. If you are not familiar with interoperability productions, see “Introduction to Productions.”

In this release, PEX supports Java and the .NET languages. PEX provides flexible connections between business services, processes, and operations that are implemented in PEX-supported languages or in InterSystems ObjectScript. In addition, you can use PEX to develop, inbound and outbound adapters. The PEX framework allows you to create an entire production in Java or .NET or to create a production that has a mix of Java, .NET, or ObjectScript components. Once integrated, the production components written in Java and .NET are called at runtime and use the PEX framework to send messages to other components in the production.

Some reasons to use the PEX framework include:

  • Developing a new production and you choose to implement it entirely in Java or .NET.

  • Creating new adapters for protocols using available Java or .NET libraries.

  • Using available Java or .NET libraries to perform complex analysis or calculations.

  • Implementing persistent messaging and long-running business processes without using ObjectScript in your application’s technology stack.

You can create the following production components using the PEX language support:

  • Inbound Adapter

  • Outbound Adapter

  • Business Service

  • Business Process

  • Business Operation

In addition to developing the code for the production components, you will typically define, configure, and monitor the production using the Management Portal. For example, you’ll use the Management Portal to create the production, configure the business services, processes, and operations, start and stop the production, and trace persistent messages running through the production.


PEX replaces the Java Business Hosts feature. For information on migrating existing Java Business Hosts productions to use PEX, see the community article Migrate from Java Business Host to PEXOpens in a new window. Java Business Hosts was deprecated in release 2019.3 and has been removed from this release.

Basic Workflow

Implementing Java and .NET components into an interoperability production consists of three basic steps:

  1. In you favorite IDE, write the business host or adapter in Java or .NET and compile the code.

  2. In the Management Portal, add a built-in PEX component that points to the new Java or .NET class. To integrate a custom Java or .NET business host into a production, use the Management Portal to open the production and add a built-in PEX business host to the production that acts as a proxy between the custom business host and the rest of the production. This built-in PEX business host has a setting that specifies the Java or .NET class of the custom business host. Integrating an adapter into the production also leverages a built-in PEX class as a proxy between the business host and the adapter written in Java or .NET.

  3. From the Management Portal or InterSystems Terminal, manually start the Java or .NET gateway. The Java gateway require Jar files containing the PEX framework in the classpath. The PEX framework requires the Java Gateway and/ or the .NET Gateway be running on the port that is defined in the settings of the built-in PEX components. For more details, see Running the Object Gateways for Java and .NET.

In Java, the PEX Java library, com.intersystems.enslib.pex, includes superclasses for each type of production component. For example, com.intersystems.enslib.pex.BusinessOperation is the superclass for business operations written in Java. Implementing a business host or adapter in Java begins by creating the appropriate subclass and overriding its methods.

In .NET, the PEX library InterSystems.EnsLib.PEX includes superclasses for each type of production component. For example, InterSystems.EnsLib.PEX.BusinessProcess is the superclass for business processes written in .NET. Implementing a business host or adapter in .NET begins by creating the appropriate subclass and overriding its methods.

In the interoperability production model, business processes are persistent objects throughout the processing of a message. Consequently, they retain the same value from initialization, processing a message, and receiving the response. . Although the Java and .NET business process objects are not persistent, the PEX framework provides the persistence for these classes. When you define a business process in Java or .NET, you define what variables will retain their values across invocations by defining them with the Persistent attribute. To specify the Persistent attribute, in Java specify @Persistent before defining the variable and in .NET, specify [Persistent] before defining the variable

Environmental Considerations

You can use InterSystems IRIS Interoperability only within an interoperability-enabled namespace that has a specific web application. When you create classes, you should avoid using reserved package names. The following subsections give the details.

Production-enabled Namespaces

An interoperability-enabled namespace is a namespace that has global mappings, routine mappings, and package mappings that make the classes, data, and menus that support productions available to it. For general information on mappings, see “Configuring Namespaces.” (You can use the information in that section to see the actual mappings in any interoperability-enabled namespace; the details may vary from release to release, but no work is necessary on your part.)

The system-provided namespaces that are created when you install InterSystems IRIS are not interoperability-enabled, except, on the community edition, the USER namespace is an interoperability-enabled namespace. Any new namespace that you create is by default interoperability-enabled. If you clear the Enable namespace for interoperability productions check box when creating a namespace, InterSystems IRIS creates the namespace with productions disabled.


All system-provided namespaces are overwritten upon reinstallation or upgrade. For this reason, InterSystems recommends that customers always work in a new namespace that you create. For information on creating a new namespace, see “Configuring Data.”

Web Application Requirement

Also, you can use a production in a namespace only if that namespace has an associated web application that is named /csp/namespace, where namespace is the namespace name. (This is the default web application name for a namespace.) For information on defining web applications, see Applications.

Reserved Package Names

In any interoperability-enabled namespace, avoid using the following package names: Ens, EnsLib, EnsPortal, or CSPX. These packages are completely replaced during the upgrade process. If you define classes in these packages, you would need to export the classes before upgrading and then import them after upgrading.

Also, InterSystems recommends that you avoid using any package names that start with Ens (case-sensitive). There are two reasons for this recommendation:

  • When you compile classes in packages with names that start with Ens, the compiler writes the generated routines into the ENSLIB system database. (The compiler does this because all routines with names that start with Ens are mapped to that database.) This means that when you upgrade the instance, thus replacing the ENSLIB database, the upgrade removes the generated routines, leaving only the class definitions. At this point, in order to use the classes, it is necessary to recompile them.

    In contrast, when you upgrade the instance, it is not necessary to recompile classes in packages with names that do not start with Ens.

  • If you define classes in packages with names that start with Ens, they are available in all interoperability-enabled namespaces, which may or may not be desirable. One consequence is that it is not possible to have two classes with the same name and different contents in different interoperability-enabled namespaces, if the package name starts with Ens.

FeedbackOpens in a new window