Data definition XML file

It is possible to create new user preferences, or override existing user preferences, by creating a custom DefaultPreferences.xml file.

A custom DefaultPreferences.xml file should be placed in the EJBServer\components\<component_name>\userpreferences directory, where <component_name> is the name of a component within the component directory.

The following sample DefaultPreferences.xml file illustrates how a user preference is defined:

Figure 1. Example of user preference definition

<Preferences>
  <PreferenceSet id="default"
       description="The default preferences">
    <Preference name="sample.pref" category="DefaultPreferences">
      <type>SVR_BOOLEAN</type>
      <value>false</value>
      <readonly>false</readonly>
      <visible>true</visible>
      <externalVisible>false</externalVisible>
    </Preference>
  </PreferenceSet>
</Preferences>

In the user preferences definition example above the preference "sample.pref" is defined in an XML document with a root Preferences node.

The Preferences document may contain only one <PreferenceSet> element, with the id attribute set to "default". The <PreferenceSet> contains any number of <Preference> elements, each defining a new preference or overriding an existing one.

The name attribute of <Preference> defines the internal name of the user preference. This attribute forms a unique name for the preference stored in the database. In the example above the name is "sample.pref".

A <Preference> element contains a number of child elements, listed in the table below.

Table 1. User Preference options
Element	Description	Mandatory	Default Value
type	Indicates the preference type, which should be a valid `Domain Definition` type.	yes	N/A
value	The initial default value of the user preference.	yes	N/A
readonly	A boolean value (true or false) that indicates whether the preference should be editable in the user preference editor in the web client.	no	false
visible	A boolean value (true or false) that indicates whether the preference should be displayed in the user preference editor in the web client for an internal user, i.e. a user on the Users table.	no	true
externalVisible	A boolean value (true or false) that indicates whether the preference should be displayed in the user preference editor in the web client for an external user.	no	false

If multiple DefaultPreferences.xml files exist (in different components), the contents of these files are merged together during a server build. The files are merged according to the SERVER_COMPONENT_ORDER. Duplicated preferences in a component with higher precedence in the SERVER_COMPONENT_ORDER will take priority over those duplicates in components with lower precedence.

The results of the merged user preferences are added to the database by the database build target for usage at runtime.

Note: Only the default value of the out of the box user preferences in Cúram should be overridden.

Although the ability to override all elements of a user preference exists it is strongly recommended that only the actual value, as defined by the <value> some_value </value> element, should be updated.