Skip to main content

Defining Other Options for Productions

This chapter describes other options that you can define or configure for an interoperability-enabled namespace.

Also see “Configuring the Message Bank Link,” later in this book.

Defining Data Lookup Tables

The Lookup Tables portal page allows you to create and configure data tables to support the Lookup and Exists utility functions. The Lookup utility function is provided so that you can easily perform a table lookup from a business rule or DTL data transformation. To avoid possible complications when exporting a lookup table, it is recommended that you avoid using special characters when naming the lookup table. As an exception, it is safe to use periods (.) in the name.

For details, see “Utility Functions for Use in Productions” in Developing Business Rules.

The Lookup function works only after you have created a lookup table and have populated it with data. You can do this selecting Interoperability, Configure, and Data Lookup Tables. If you click Open, a dialog box lists the lookup tables that are defined in the namespace. Select a lookup table and InterSystems IRIS® displays the following form:

Lookup Table Management Portal page

To edit entries in a lookup table, you can:

  • Delete an entry by selecting the red X icon. The entry is deleted when you save the table. Until you have saved the table, you can restore the entry by selecting the green + icon that is displayed to the left of the entry.

  • Update an entry by entering the same key as the entry and a new value in the form on the right and then selecting Apply. After you update the value, the original value is displayed in the Original Value column until you save the lookup table. Selecting an existing entry populates the form on the right with the entry’s current values.

  • Add a new entry by entering a new key and its value in the form on the right and selecting Apply.

  • Undo the previous action by selecting the curved arrow in the menu bar.


Selecting an entry has only one effect: initializing the values in the form on the right. Selecting Apply acts on the entry specified in the Key field not on the selected entry. If the key field matches an existing entry, that entry is updated. If the key field does not match an existing entry, then a new entry is added. Selecting the green + icon on the menu bar or selecting Discard clears the form but does not have any other effect.

You can take an action by selecting one of the following buttons:

  • New—Displays a form so that you can name the lookup table and then displays the empty table. Add entries to the table by entering in key and value pairs and selecting Apply for each pair. You must select Save to make the lookup table permanent.

  • Open—Displays the lookup tables defined in the current namespace and allows you to select one.

  • Save—Saves the current lookup table with any edits that you have applied. Clears the Original Value column and removes deleted records.

  • Save As—Saves the current table entries to a new table. Specify the new table name and select OK. Clears the Original Value column and removes deleted records.

  • Delete—Deletes the current table. If you have made any edits to the table since opening it, InterSystems IRIS asks if you want to leave the page. To delete the table, select Leave Page. If you select Stay on Page, InterSystems IRIS treats the current table as if it were a new table.

  • There are two ways to import lookup tables: Import Legacy and Import . An important difference between them is that when you are importing a lookup table with the same name as an existing lookup table, Import Legacy merges the existing table with the data from the file and Import replaces the existing lookup table with the data from the file.

    • Import Legacy—Imports the lookup tables defined in the file. If an imported lookup table has the same name as an existing table, the values are merged. If a key is defined in the file, it overwrites any existing value of that key in the lookup table.

    • Import—Adds new lookup tables that are defined in an XML file. If any of the new tables have the same name as an existing table, the new table replaces the old one. Select Browse to specify an XML file, then select Open. The form displays the LookUp Table (LUT) document or documents defined in the file. You can select all of the lookup tables or some of the lookup tables listed, then select Import to import the lookup table(s). The Import button can only import the new file format (see following note).


    There are two lookup table file formats: a new format and the legacy format. The new format contains additional XML Document tags. Import Legacy can handle both the new and the legacy format, but Import can only handle the new format. The new format is exported by Studio and by the Export portal button. The old format is exported by the Ens.Util.LookupTable.%Export() method. See Lookup Table File Format for a description of the lookup table file formats.

  • Export—Exports the current table to an XML file. Although you can specify the name of the file, the lookup table exported has the same name as the current lookup table and does not use the file name. You can export only using the current XML format; you cannot export the legacy XML format with this release.

    If you used special characters when naming the lookup table, you may encounter issues when exporting the table. As a workaround, you can export the entire ^Ens.LookupTable global rather than an individual table. For details, see Exporting Globals. Alternatively, you can export the global subscript that corresponds to the name of a lookup table. For example, to export the lookup table My/Lookup/Table, call:

     set st = $SYSTEM.OBJ.Export("Ens.LookupTable(""My/Lookup/Table"").GBL","filename.xml")

You cannot undo the Delete, Import, or Import Legacy operation.


If there is an existing lookup table with the same name, the Import button has a different behavior from the Import Legacy button. The Import button completely replaces the contents of the existing lookup table. In contrast, the Import Legacy button merges the new values with the existing values.

For information on working with lookup tables in programs, see “Programmatically Working with Lookup Tables” in Developing Productions.

The following subsections describe:

Lookup Table File Format

There are two XML formats that describe lookup tables: the new format and the legacy format.

The new Lookup Table XML format consists of one or more XML Document elements, for example:

<?xml version="1.0" encoding="UTF-8"?>
  ts="2014-10-21 11:52:51">
  <Document name="AlertTable.LUT">
      <entry table="AlertTable" key="BadMessageHandler">temp_1@company.test</entry>
      <entry table="AlertTable" key="Extra_Observations">temp_5@company.test</entry>
      <entry table="AlertTable" key="MsgRouter">temp_3@home.test</entry>
      <entry table="AlertTable" key="Priority_FileOperation">temp_5@home.test</entry>
      <entry table="AlertTable" key="Regular_FileOperation">temp_4@company.test</entry>

The XML elements have the following syntax:

  • Each Document element must has a name attribute that specifies the lookup table name and has a file type .LUT.

  • Each Document element contains one lookupTable element.

  • Each lookupTable element contains a list of entry elements.

  • Each entry element has a table attribute that specifies the same table name as specified in the Document name, specifies a key attribute, and specifies the value of the entry as text.

The legacy format exported by the Ens.Util.LookupTable.%Export() method does not have the Document element. It consists of just a single lookupTable element and the entry elements that it contains. It can contain entries for multiple lookup tables by specifying different names in the table element.

Importing Flat Files as Data Lookup Tables

You can import a flat file as a data lookup table, if the file is as follows:

  • It can include a header row.

  • It must include three values, separated by spaces, commas, tabs, or another delimiter.

  • From left to right, the three values must correspond to the Value column of a lookup table, the Key value of a lookup table, and the desired name of the lookup table.

To import such a file as a lookup table, use the Data Import Wizard, as described in “Importing Data from a Text File” in Using InterSystems SQL. For the schema name, use Ens_Util. For the table name, use LookupTable.

Defining System Default Settings

This section discusses system default settings. It includes the following sections:

Purpose of System Default Settings

The purpose of system default settings is to simplify the process of copying a production definition from one environment to another. In any production, the values of some settings are determined as part of the production design; these settings should usually be the same in all environments. Other settings, however, must be adjusted to the environment; these settings include file paths, port numbers, and so on.

System default settings should specify only the values that are specific to the environment where InterSystems IRIS is installed. In contrast, the production definition should specify the values for settings that should be the same in all environments.

To find the value for a setting for a production, business host, or adapter, InterSystems IRIS searches the following locations, in order:

  1. The production definition. If InterSystems IRIS finds a value for a setting here (even if the value is an empty string), it uses that value.

  2. The system default settings, which are stored outside the production definition.

    If InterSystems IRIS finds a value here (even if the value is an empty string), it uses that value.

  3. The value of the setting as specified in the definition of the class on which the production, business host, or adapter is based.

    InterSystems IRIS uses this value only if there is no system default for the setting.

    Some settings do not have any default value.

When you configure a production, the labels are color-coded to indicate whether the value was set in the production, the system default settings, or the class definition. See Understanding the Color Coding for Settings for more information.

Accessing the System Default Settings

To access the System Default Settings page, select Interoperability > Configure > System Default Settings. The System Default Settings page displays the settings defined in the namespace:

System Default Settings Management Portal page

To create a new system default setting, click New. To edit an existing setting, select the setting and click Edit. To delete a setting, select the setting and click Delete.


Security privileges may restrict you from creating, editing, or deleting some of the system default settings. For information about these security privileges, see Security for System Default Settings.

The following elements define a system default setting:

  • Production Name—Optionally, specifies the production to which this default applies. If set to *, this default applies to all productions in the namespace.


    You cannot change the value of this field once you save the default. You must delete the default and create a new one.

  • Item Name—Optional, specifies the business host to which this default applies. If set to *, this default applies to all hosts in the production or in all productions.

  • Host Class Name—Optional, specifies the class of the business host to which this default applies. If set to *, this default applies to all hosts in the production or in all productions.

  • Setting Name—Specifies the name of the property to set. Note that property names do not include spaces. In most cases, the property name is similar to the setting name, with the spaces removed. For example, the setting Log Trace Events is based on a property called LogTraceEvents.


    You can see the property name within the popup window that displays descriptive text for the setting.

  • Setting Value—Specifies the value to assign to the property. If this field is blank; it sets the default to an empty string.

  • Description—Optional, specifies a description of the default.

  • Deployable—If set, the system default setting can be deployed to another production. For more information about deployment, see Deploying a Production.

Creating or Editing a System Default Setting

If you are creating a new system default setting or editing an existing one, InterSystems IRIS displays the following form:

System Default Setting page with the ShutdownTimeout setting set to 180

The System Default Setting page allows you to create a new system default setting or edit an existing one. For convenience it displays a tree of productions and other classes. This allows you to find existing settings and drag the names and values to the form. The Expand Tree and Contract Tree buttons and the plus and minus icons allow you to explore the tree to locate the property you are seeking.

While you can use an asterisk (*) in theProduction, Item Name, and Host Class Name fields to apply a setting to all the productions in a namespace, you cannot use other wildcard input such as EnsLib*. Additionally, you can specify only one value in each of these fields.


Your security privileges determine which system default settings appear in the tree. For information about these security privileges, see “Security for System Default Settings” in Managing Productions.

When you have completed defining or updating the system default setting, click Save. The Cancel button discards any changes and returns to the list of system default settings without creating or updating a setting. The Restore button returns to fields to their initial values and allows you to edit the values.

Using System Default Settings

When using a wizard to create the business service or operation, use the Default applies if no value check box to specify that you want to use system default settings when available. This option is selected by default.

Without the Default applies if no value option, the business host is created with blank values, not the system defaults. In this case, you must manually change the value of the setting to the default on the Settings tab of the Production Configuration window. For instructions, see Restoring a Setting to Its Default Value.

Configuring Default Settings for Manually Purging Production Data

As productions run in a given namespace, InterSystems IRIS may write entries to the Event Log, message warehouse, business process log, business rule log, and I/O archive log for the namespace. Since the entries can accumulate over time and consume large amounts of disk space, InterSystems IRIS enables you and other users with appropriate permissions to purge outdated entries. You can do so manually; that is, you can purge production data on an ad hoc basis. You can also schedule regular purges. For more information, see Purging Production Data.

InterSystems IRIS enables you to configure default settings for manual purges. The defaults apply on the Purge Management Data page and can be overridden only by users with appropriate permissions. For more information, see Controlling Access to Management Portal Functions.

To configure default settings for manual purges in a namespace, navigate to Interoperability > Configure > Purge Data Settings in the namespace. Alternatively, set the following nodes of the ^Ens.Configuration global for the namespace:


Purges are irreversible and can lead to unintentionally orphaned data or the loss of unresolved requests. Consequently, InterSystems recommends that you carefully review the descriptions of the settings in Settings for Purging Data before you configure them.

Configuring Source Control Settings

There is a flag to indicate whether the source control system requires a project context to be supplied to work correctly. The flag is activated as follows:

 Set ^%SYS("Ensemble","SourceControl", $namespace, "ProjectContext") = 1

Existing user templates used as dialog windows in Studio must include the Ens_SourceControl.js in /csp/broker/ensemble/ (which can be referenced by the path ensemble/Ens_SourceControl.js) to manage your browser-based interactions. This inclusion is required both for any web pages. Depending on the context required by your source control hooks, you may need to add some extra data to certain returns.

You can configure source control settings for each interoperability-enabled namespace. For information on this, see Integrating InterSystems IRIS with Source Control Systems.

The Production Configuration Page, which you reach by selecting Interoperability > Configure > Production, supports source control by default. If you want to exclude the Production Configuration Page from source control, select Interoperability > Manage > Configuration > Interoperability Settings and select the check box labeled Exclude Production Configuration Page from Source Control: then Apply.

When source control is in use, source control buttons appear on the page:

Source Control Commands button – Source Control Commands

View Source Control Output buttonView Source Control Output

Click the Source Control Commands button to see available commands. The exact menu of commands depends on the current state of the production with respect to source control, as well as the source control implementation. The appearance of the View Source Control Output button changes to View Source Control Output Button with new output when there is new output to be viewed.

The following Management Interoperability browser based editors also support Source Control hooks:

  • Interoperability > Configure > Data Lookup Tables

  • Interoperability > Build > Business Processes

  • Interoperability > Build > Data Transformations

  • Interoperability > Build > Business Rules

  • Interoperability > Build > Record Maps

  • Interoperability > Build > Complex Record Mapper


If a production is under source control and you do not have it checked out for update, you cannot modify the production definition. You can temporarily Stop, Start, and Restart business hosts by using the buttons on the Action tab. These buttons temporarily stop or start the host but do not modify the production definition. A business host can only be temporarily stopped if it has a pool size greater than 1 or in the case of Business Processes and Business Operations are invoked Queue and not InProc.

Configuring a Mirror Virtual IP as the Network Interface

If you set up a mirror virtual IP (VIP) in your environment, you can optionally specify the VIP as the destination for connections from some production components. Specifically, you can use the VIP for outgoing connections when the production component has a Local Interface setting. For example, TCP adapters have a Local Interface setting, which you can set to the VIP.