Adding and Removing Settings

Adding Settings

To provide new settings for a production, a business host, or an adapter, modify its class definition as follows:

1. Add a property for each configuration setting you wish to define.

2. Add a class parameter called SETTINGS to the class.

3. Set the value of SETTINGS to be a comma-delimited list of the names of the properties you have just defined. For example:

   Property foo As %String;
   
   Property bar As %String;
   
   Parameter SETTINGS = "foo,bar";
   

   

   See the following section for additional details for SETTINGS.

The foo and bar settings now automatically appear in the configuration display on the Production Configuration page whenever an item of that class is selected for configuration.

It is possible to have a property with the same name within an adapter class and within a business host class that uses the given adapter. It is also possible to expose both of these properties as settings. The Production Configuration page displays these settings separately with separate tool tips generated by the property definitions in the respective classes.

Removing Settings

To remove an inherited configuration setting, for a production, a business host, or an adapter, modify its class definition as follows. Update the SETTINGS class parameter of that class to include the setting name, preceded by a hyphen (-). For example:

Parameter SETTINGS = "-foo";

Note that by design, some settings cannot be removed; for example, the Pool Size setting cannot be removed.

Specifying Categories and Controls

By default, a setting is displayed in the Additional Settings category on the Details tab when you configure a production. By default, the setting provides one of the following input mechanisms, depending on the property on which the setting is based:

• In most cases, the setting is displayed with a plain input field.

• If the property specifies the VALUELIST parameter, the setting is displayed with a drop-down list. The items that will appear in the drop-down list must be separated using a comma as the delimiter.

• If the property is of type %BooleanOpens in a new tab, the setting is displayed as a check box.

In all cases, the InitialExpression of the property (if specified) controls the initial state of the input field.

You can override both the location and control type. To do so, include the setting name in SETTINGS as follows:

Parameter SETTINGS = "somesetting:category:control";

Or:

Parameter SETTINGS = "somesetting:category";

Parameter SETTINGS = "somesetting::control";

Where category and control indicate the category and control to use, respectively. The following subsections provide details.

You can include multiple settings, as follows:

Parameter SETTINGS = "setting1:category:control1,setting2:control2:editor,setting3:category:control3";

For example (with disallowed line breaks included):

Parameter SETTINGS = "HTTPServer:Basic,HTTPPort:Basic,SSLConfig:Connection:sslConfigSelector,
ProxyServer:Connection,ProxyPort:Connection,ProxyHTTPS:Connection,
URL:Basic,Credentials:Basic:credentialsSelector,UseCookies,ResponseTimeout:Connection" 

Available Categories

Within the SETTINGS parameter, category is one of the following case-sensitive, literal values:

• Info—Places the setting into the Information Settings category.

• Basic—Places the setting into the Basic Settings category.

• Connection—Places the setting into the Connection Settings category.

• Additional—Places the setting into the Additional Settings category (the default).

• Alerting—Places the setting into the Alerting Control category.

• Dev—Places the setting into the Development and Debugging category.

Or use your own category name.

Available Controls

Within the SETTINGS parameter, control specifies the name of a specific control to use when viewing and modifying the setting in the Production Configuration page. Use selector or use the name of a class in the package EnsPortal.Component. See Examples for Settings Controls.

To supply extra values to your component in order to display a suitable set of options, append a set of name-value pairs as follows:

myControl?Prop1=Value1&Prop2=Value2&Prop3=Value3

Where:

• Prop1, Prop2, Prop3, and so on are names of properties of the control. For example: multiSelect

• Value1, Value2, Value3, and so on are the corresponding values.

  Use the syntax @propertyname to refer to a property of the JavaScript zenPage object. The supported variables are these:

  • currHostId refers to the ID of the current Ens.Config.ItemOpens in a new tab.

  • productionId refers to the ID of the Ens.Config.ProductionOpens in a new tab in use.

  Use \@ to indicate the character @ as is.

  To pass values to the context property of a control, enclose the value in curly braces. See the subsection.

The selector Control

InterSystems IRIS uses the general-purpose selector component, which you can also use; to do so, specify control as selector and then append property/value pairs.

The selector component allows almost any list of data or options to be displayed to the user and which allows the user to type data if needed. To configure the component in this way, use the following syntax to set the context property of the control:

context={ContextClass/ContextMethod?Arg1=Value1&Arg2=Value2&Arg3=Value3}

Where:

• ContextClass is the name of the context class. This must be a subclass of %ZEN.Portal.ContextSearchOpens in a new tab or Ens.ContextSearchOpens in a new tab. See Examples for Settings Controls.

• ContextMethod is a method in that class. This method provides the data from which the user chooses values.

• Arg1, Arg2, Arg3, and so on are the names of multidimensional arguments of that method.

• Value1, Value2, Value3, and so on are values for those arguments. The rules for values are the same as given previously (for example, you can use @propertyname).

Note:

Note that the selector component also has a property named multiSelect. By default, the user can select only one item. To enable the user to select multiple items, include a property/value pair as follows: multiSelect=1.

The argument names and values must be URL encoded. For example, replace % with %25.

Examples for Settings Controls

The following list gives examples for control, organized by the kind of data that they enable the user to select.

These examples use InterSystems IRIS classes. Many of these examples use the Ens.ContextSearchOpens in a new tab class, which provides a large number of useful methods. If this list does not cover your scenario, see the class documentation for Ens.ContextSearchOpens in a new tab to determine whether any of the existing methods supply the data you need. If that class does not cover your scenario, you can create your own subclass of Ens.ContextSearchOpens in a new tab.

BPL

bplSelector

business hosts in the same production

selector?multiSelect=1&context={Ens.ContextSearch/ProductionItems?targets=1&productionName=@productionId}

Or, if the user should choose only one business host:

selector?context={Ens.ContextSearch/ProductionItems?targets=1&productionName=@productionId}

business partners

partnerSelector

business rules

ruleSelector

character sets

selector?context={Ens.ContextSearch/CharacterSets}

credential sets

credentialsSelector

directories

directorySelector

DTL

dtlSelector

files

fileSelector

framing

selector?context={Ens.ContextSearch/getDisplayList?host=@currHostId&prop=Framing}

local interfaces

selector?context={Ens.ContextSearch/TCPLocalInterfaces}

schema categories appropriate for a specific business host

selector?context={Ens.ContextSearch/SchemaCategories?host=classname}

Where classname is the class name of the business host. For example:

selector?context={Ens.ContextSearch/SearchTableClasses?host=EnsLib.MsgRouter.RoutingEngineST}

schedules

scheduleSelector

search table classes appropriate for a specific business host

selector?context={Ens.ContextSearch/SearchTableClasses?host=classname}

Where classname is the class name of the business host. For example:

selector?context={Ens.ContextSearch/SearchTableClasses?host=EnsLib.EDI.EDIFACT.Service.Standard}

SSL configurations

sslConfigSelector

Specifying Default Values

You should consider how to control the default values for any settings of those items. InterSystems IRIS can take the default value for a setting from one of three sources:

• The production definition.

• The values defined for the InterSystems IRIS instance, but stored outside the production. For information, see Defining Production Defaults.

• The default value for the property as defined in the host class. In this case, the default value is determined by the InitialExpression property keyword.

Some settings are dependent on the environment, such as TCP/IP addresses or file paths; typically you configure these settings to have their source outside the production, while others, such as ReplyCodeActions are design decisions and most likely you develop your application to retrieve these from the production definition.

You can develop your production to have configuration settings come from different sources. The primary purpose is to make it easier to move productions from one InterSystems IRIS instance to another, such as from test to live.

Once you define a production, you can change the source of both production and business host settings on the Production Configuration page of the Management Portal; see Configuring Settings.

The use of default settings allows you to define production and business host settings outside the production definition where you can preserve them during a production upgrade. To facilitate updating productions or moving productions from one system to another, you can omit settings and take their values from a structure that is installed on the system. When a setting is missing, InterSystems IRIS retrieves the default setting from outside the production definition if one exists.

For programming details, see Ens.DirectorOpens in a new tab class for the method signatures for the following methods:

• GetProductionSettingValue()

• GetProductionSettings()