This is documentation for Caché & Ensemble.

For information on converting to InterSystems IRIS, see the InterSystems IRIS Adoption Guide and the InterSystems IRIS In-Place Conversion Guide, both available on the WRC Distributions page (login required).

Home > Class Reference > ENSLIB namespace > Ens.Config.Item


persistent class Ens.Config.Item extends %Library.Persistent, %XML.Adaptor

SQL Table Name: Ens_Config.Item

Property Inventory

Method Inventory


parameter DOMAIN = Ensemble;
parameter XMLIGNORENULL = 1;
Inherited description: XMLIGNORENULL allows the programmer to override the default XML handling of empty strings for properties of type %String. By default (XMLIGNORENULL = 0), empty strings in the XML input are stored as $c(0) and $c(0) is written to XML as an empty tag. A missing tag in the XML input is always stored as "" and "" is always output to XML as no tag.

If XMLIGNORENULL is set = 1, then both missing tags in the XML and empty strings are input as "", and both "" and $c(0) are output as empty tags (i.e. <tag></tag>).

If XMLIGNORENULL is set = "inputonly", then both missing tags in the XML and empty strings are input as "". Output of "" and $c(0) are for XMLIGNORENULL = 0: $c(0) is output as an empty tag (i.e. <tag></tag>) and "" is output as no tag.

If XMLIGNORENULL = "runtime" (runtime is not case sensitive), then the behavior of XMLIGNORENULL is determined by the format parameter of XMLExport, XMLImport and %XML.Reader.OpenFile. The default behavior for XMLIGNORENULL="runtime is the same as XMLIGNORENULL=0. Adding "ignorenull" to the format argument changes the behavior to that of XMLIGNORENULL=1. "ignorenull" shoud be separated by a comma from literal/encoded part of the format. Example values for format are "", ",ignorenull", "literal,ignorenull" and "encoded,ignorenull". Note that "inputonly" is equivalent to using ,ignorenull for XMLExport and not for %XML.Reader.


property AlertGroups as %String (MAXLEN = 2500, XMLPROJECTION = "NONE");
A computed property to reflect the values specified in the AlertGroups setting in Settings. The primary purpose of this property is to allow us to build the AlertGroup index on all the individual group values in the string. The actual breaking down of this value is performed in AlertGroupBuildValueArray()().
Property methods: AlertGroupsBuildValueArray(), AlertGroupsCompute(), AlertGroupsDisplayToLogical(), AlertGroupsGet(), AlertGroupsGetStored(), AlertGroupsIsValid(), AlertGroupsLogicalToDisplay(), AlertGroupsLogicalToOdbc(), AlertGroupsNormalize(), AlertGroupsSQLCompute(), AlertGroupsSet(), AlertGroupsSetT()
property Category as %String (MAXLEN = 2500, XMLPROJECTION = "ATTRIBUTE");
Optional list of categories this item belongs to, comma-separated. This is only used for display purposes and does not affect the behavior of this item.
Property methods: CategoryDisplayToLogical(), CategoryGet(), CategoryGetStored(), CategoryIsValid(), CategoryLogicalToDisplay(), CategoryLogicalToOdbc(), CategoryNormalize(), CategorySet()
property ClassName as %String (MAXLEN = 128, XMLPROJECTION = "ATTRIBUTE") [ Required ];
Class name of this config item.
Property methods: ClassNameDisplayToLogical(), ClassNameGet(), ClassNameGetStored(), ClassNameIsValid(), ClassNameLogicalToDisplay(), ClassNameLogicalToOdbc(), ClassNameNormalize(), ClassNameSet()
property Comment as %String (MAXLEN = 512, XMLPROJECTION = "ATTRIBUTE");
Optional comment text for this component.
Property methods: CommentDisplayToLogical(), CommentGet(), CommentGetStored(), CommentIsValid(), CommentLogicalToDisplay(), CommentLogicalToOdbc(), CommentNormalize(), CommentOrClassnameDisplayToLogical(), CommentOrClassnameGet(), CommentOrClassnameIsValid(), CommentOrClassnameLogicalToDisplay(), CommentOrClassnameLogicalToOdbc(), CommentOrClassnameNormalize(), CommentSet()
property CommentOrClassname as %String (XMLPROJECTION = "NONE") [ Calculated , Transient , ReadOnly ];
Calculated comment-or-classname property.
Property methods: CommentOrClassnameDisplayToLogical(), CommentOrClassnameGet(), CommentOrClassnameIsValid(), CommentOrClassnameLogicalToDisplay(), CommentOrClassnameLogicalToOdbc(), CommentOrClassnameNormalize()
property DisableErrorTraps as %Boolean (XMLPROJECTION = "ATTRIBUTE");
Deprecated - Always 0 : Whether to disable error traps for the job or not.
Property methods: DisableErrorTrapsDisplayToLogical(), DisableErrorTrapsGet(), DisableErrorTrapsGetStored(), DisableErrorTrapsIsValid(), DisableErrorTrapsLogicalToDisplay(), DisableErrorTrapsLogicalToXSD(), DisableErrorTrapsNormalize(), DisableErrorTrapsSet(), DisableErrorTrapsXSDToLogical()
property Enabled as %Boolean (XMLPROJECTION = "ATTRIBUTE") [ InitialExpression = 1 ];
Whether this config item is enabled or not.
Property methods: EnabledDisplayToLogical(), EnabledGet(), EnabledGetStored(), EnabledIsValid(), EnabledLogicalToDisplay(), EnabledLogicalToXSD(), EnabledNormalize(), EnabledSet(), EnabledXSDToLogical()
property Foreground as %Boolean (XMLPROJECTION = "ATTRIBUTE") [ InitialExpression = 0 ];
Whether to run the job of this config item in the foreground or background.
Property methods: ForegroundDisplayToLogical(), ForegroundGet(), ForegroundGetStored(), ForegroundIsValid(), ForegroundLogicalToDisplay(), ForegroundLogicalToXSD(), ForegroundNormalize(), ForegroundSet(), ForegroundXSDToLogical()
property InactivityTimeout as %Numeric (MINVAL = 0, XMLIO = "IN", XMLPROJECTION = "ATTRIBUTE") [ Calculated , Transient ];
This property is now a shadow of a Host Config Setting of the same name.
Property methods: InactivityTimeoutDisplayToLogical(), InactivityTimeoutGet(), InactivityTimeoutIsValid(), InactivityTimeoutLogicalToDisplay(), InactivityTimeoutNormalize(), InactivityTimeoutSet(), InactivityTimeoutXSDToLogical()
property LogTraceEvents as %Boolean (XMLPROJECTION = "ATTRIBUTE") [ InitialExpression = 0 ];
Whether to log trace events for this item.
Property methods: LogTraceEventsDisplayToLogical(), LogTraceEventsGet(), LogTraceEventsGetStored(), LogTraceEventsIsValid(), LogTraceEventsLogicalToDisplay(), LogTraceEventsLogicalToXSD(), LogTraceEventsNormalize(), LogTraceEventsSet(), LogTraceEventsXSDToLogical()
property ModifiedSettings as list of Ens.Config.Setting (XMLPROJECTION = "NONE") [ Transient ];
Same format as Settings. You must call PopulateModifiedSettings() to populate this collection. The collection contains the list of settings that are either defined in the production, or have default setting overrides.
Property methods: ModifiedSettingsBuildValueArray(), ModifiedSettingsCollectionToDisplay(), ModifiedSettingsCollectionToOdbc(), ModifiedSettingsDisplayToCollection(), ModifiedSettingsGet(), ModifiedSettingsGetObject(), ModifiedSettingsGetObjectId(), ModifiedSettingsGetSwizzled(), ModifiedSettingsIsValid(), ModifiedSettingsOdbcToCollection(), ModifiedSettingsSet(), ModifiedSettingsSetObject(), ModifiedSettingsSetObjectId()
property Name as %String (MAXLEN = 128, XMLPROJECTION = "ATTRIBUTE") [ Required ];
The name of this config item. Default is the class name.
Property methods: NameDisplayToLogical(), NameExists(), NameGet(), NameGetStored(), NameIsValid(), NameLogicalToDisplay(), NameLogicalToOdbc(), NameNormalize(), NameSet()
property PoolSize as %Integer (MINVAL = 0, XMLPROJECTION = "ATTRIBUTE");
Number of jobs to start for this config item.
Default value:
0 for Business Processes (i.e. use shared Actor Pool)
1 for FIFO message router Business Processes (i.e. use a dedicated job)
1 for Business Operations
0 for adapterless Business Services
1 for others
For TCP based Services with JobPerConnection=1, this value is used to limit the number of connection jobs if its value is greater than 1. A value of 0 or 1 places no limit on the number of connection jobs.
Property methods: PoolSizeDisplayToLogical(), PoolSizeGet(), PoolSizeGetStored(), PoolSizeIsValid(), PoolSizeLogicalToDisplay(), PoolSizeNormalize(), PoolSizeSet(), PoolSizeXSDToLogical()
property Production as Ens.Config.Production (XMLPROJECTION = "NONE");
Reference to the Production object.
Property methods: ProductionGet(), ProductionGetObject(), ProductionGetObjectId(), ProductionGetStored(), ProductionGetSwizzled(), ProductionIsValid(), ProductionNewObject(), ProductionSet(), ProductionSetObject(), ProductionSetObjectId(), ProductionUnSwizzle()
property Schedule as %String);
Specifies times when this item should be stopped and restarted. You may enter a string formatted as a comma-separated list of event specifications, or you may enter the name of a schedule specification preceded by the @ symbol. To create a named schedule specification, use the Ensemble > Configure > Schedule Specs page.

If you wish to simply enter an event specification string in this field, it must use the following format:


Where each item in the event specification, from left to right, has the values described below:

  • action - must be either START or STOP
  • : - Required separator
  • YYYY-MM-DD - This part of the string must have one of the following two syntaxes:
    • YYYY is the year as 4 numerals, MM is the month as 2 numerals and DD is the day of the month as 2 numerals.
      Any of these fields may be the single character * (asterisk) indicating all years, all months, or all days.
    • YYYY is the string WEEK, MM is the specific occurrence of the day of the week (indicated by DD) in the month (01 = first occurrence of the specific day of the week in the month, 02 = second occurrence in the month, etc.), and DD is a specific day of the week (00 = Sunday, 01 = Monday, etc.).
      MM may be * for all occurrences and DD may be * for all days.
    Note that once a field is specified as *, all fields to the left of it are also assumed to be *. Thus, if the DD value is *, the MM value is treated as * even if it has a specific numeric value. Similarly, if MM is *, YYYY is treated as *.
  • T - Required separator
  • hh:mm:ss - Hour, minute, and second
  • , - Use the comma separator only if there is another event specification after the current one. Do not use it at the end of the Schedule string.

For example, to start the configuration item every day at 8 a.m. and stop it every day at 5 p.m. you could use the following schedule string:


As described at the beginning of this topic, you can also create a named schedule string. Assuming you named your schedule 'Daytime', you could then refer to your named schedule as follows:

Property methods: ScheduleDisplayToLogical(), ScheduleGet(), ScheduleGetStored(), ScheduleIsValid(), ScheduleLogicalToDisplay(), ScheduleLogicalToOdbc(), ScheduleNormalize(), ScheduleSet()
property Settings as list of Ens.Config.Setting (XMLNAME = "Setting", XMLPROJECTION = "ELEMENT");
Adapter and host settings specified for the adapter object and the host object.
Property methods: SettingsBuildValueArray(), SettingsCollectionToDisplay(), SettingsCollectionToOdbc(), SettingsDisplayToCollection(), SettingsGet(), SettingsGetObject(), SettingsGetObjectId(), SettingsGetStored(), SettingsGetSwizzled(), SettingsIsValid(), SettingsOdbcToCollection(), SettingsSet(), SettingsSetObject(), SettingsSetObjectId()
property VirtualSettings as list of %String (XMLPROJECTION = "NONE") [ Transient ];
Contains the list of settings, value, value_type, default, default_type and other meta information. Must call PopulateVirtualSettings() to populate this collection. The format of value of each element is the following:
$LB(Target, Name, Value, ValueType, Default, DefaultType, Description, Type, MAXLEN, MINVAL, MAXVAL, VALUELIST, DISPLAYLIST, IsRequired)
Property methods: VirtualSettingsBuildValueArray(), VirtualSettingsCollectionToDisplay(), VirtualSettingsCollectionToOdbc(), VirtualSettingsDisplayToCollection(), VirtualSettingsDisplayToLogical(), VirtualSettingsGet(), VirtualSettingsGetObject(), VirtualSettingsGetObjectId(), VirtualSettingsGetSwizzled(), VirtualSettingsIsValid(), VirtualSettingsLogicalToDisplay(), VirtualSettingsLogicalToOdbc(), VirtualSettingsNormalize(), VirtualSettingsOdbcToCollection(), VirtualSettingsSet(), VirtualSettingsSetObject(), VirtualSettingsSetObjectId()


method AdapterClassName() as %String
Name of the Adapter class used by this config item.
classmethod AlertGroupsBuildValueArray(pAlertGroups As %String = "", Output pValueArray As %String) as %Status
Helper method to allow the individual values in AlertGroups to be indexed.
method BusinessType() as %String
The Business type of this config item.
method CheckForIllegalCharacters(pName As %String) as %Status
Check for characters that are illegal in configuration item names. Characters | ; , : [ are not allowed at all, characters ! - $ are not allowed as first or last character, and character * is not allowed as the whole config name.
method Checksum() as %Integer
Checksum used in updating production.
method CommentOrClassnameGet() as %String
classmethod ComputeAlertGroups(pSettings) as %String
Method to compute the value of AlertGroups based on the value of the AlertGroups setting in the serialized Settings list passed in as pSettings.
method FindSettingByName(pSettingName As %String, pTarget As %String = "") as Setting
Locate the first setting with a given name.
classmethod GetBusinessType(pClassname As %String, pThisObject As Ens.Config.Item) as %String
Get the business type of the config item. The return value macros are defined in
method GetModifiedSetting(pSettingName As %String, ByRef pValue As %String) as %Boolean
Get the config value of the named setting including resolution of system default settings, return 0 if not defined, 1 if defined.
method GetSetting(pSettingName As %String, ByRef pValue As %String) as %Boolean
Get the config value of the named setting, return 0 if not defined, 1 if defined.
method GetStaticSettings(ByRef pList) as %Status
Return a list of all the common static settings properties for the current config item.
method InactivityTimeoutGet() as %Numeric
Retrieve the value of InactivityTimeout from the InactivityTimeout setting in Settings.
method InactivityTimeoutSet(%newval) as %Status
Ensure that changes to InactivityTimeout are pushed into the InactivityTimeout setting in Settings.
method PopulateModifiedSettings() as %Status
Call this method to initialize the ModifiedSettings collection. The collection includes settings defined in the Production as well as those ones with default setting overrides.
method PopulateVirtualSettings() as %Status
Populate the VirtualSettings collection.
method QueueName() as %String
Queue name used by this config item.
method UpdateSettings(pArray) as %Status
This method updates the settings collection with the data from pArray. The settings collection is cleared first, then the entries in pArray are used to update it. The format of pArray is the following:
pArray = total number of entries
pArray(i) = $LB(Target, Name, Value)


index (AlertGroup on Production:Exact,AlertGroups(ELEMENTS):Exact);
Index on all the group names defined in AlertGroups. The production is included in the index to ensure that the available values are correct for each production.
Index methods: AlertGroupsBuildValueArray(), AlertGroupsCompute(), AlertGroupsDisplayToLogical(), AlertGroupsGet(), AlertGroupsGetStored(), AlertGroupsIsValid(), AlertGroupsLogicalToDisplay(), AlertGroupsLogicalToOdbc(), AlertGroupsNormalize(), AlertGroupsSQLCompute(), AlertGroupsSet(), AlertGroupsSetT()
index (Name on Production:Exact,Name:Exact);
Index on the name of the config item as well as which production it is associated with.
Index methods: NameDisplayToLogical(), NameExists(), NameGet(), NameGetStored(), NameIsValid(), NameLogicalToDisplay(), NameLogicalToOdbc(), NameNormalize(), NameSet()


trigger OnChange (AFTER event INSERT/UPDATE/DELETE);
Ensure we update the modified flag after SQL changes.

Inherited Members

Inherited Methods


Storage Model: CacheStorage (Ens.Config.Item)