Roles

A '''Role''' is a logical collection of sipXecs services. Since some services work closely together, the role abstraction simplifies administration by collecting these related services into groups - rather than having to assign individual services to servers and understand the (constantly changing) relationships between them, the administrator just assigns roles to servers and lets sipXconfig worry about the details.

A sipXecs server can be assigned to provide various PBX related capacities: ACD (Automated Call Distribution), SIP Trunking, Conferencing, Instant Messaging, Management, SIP Router, and Voicemail. The administrator configures these capabilities by assigning roles to defined servers. These capacities are assigned in the System>Server>Server Roles screen. When there are multiple servers in a system, a role might be assigned to a dedicated server to enhance performance. By default, all roles are enabled in a server.

Role Definitions

During initialization, roles are configured by the file sipXconfig/neoconf/src/org/sipfoundry/sipxconfig/service/bundle.beans.xml. Each role is a bundle bean, and all beans are children of an abstract bundle. The "autoEnable" properties controls whether a bundle (role) is enabled or not. Since the abstract bundle has the property "autoEnable" set to true, all roles are enabled by default.

<bean id="abstractBundle" abstract="true">
<property name="autoEnable" value="true" />
<property name="resetAffectLocation" value="false" />
</bean>

The following table relates the Role as seen in the GUI to the bundles names and bean id in the bundle.beans.xml file.

Bundle Properties

All bundle beans shares the same SipxServiceBundle class implementation. Besides the unique bean id, all bundle beans' constructor-arg value is passed into the SipxServiceBundle class to identify the bundle.

The following table describes some of the properties in a bundle bean:

By reading a role's property values, one can note the supported instances of a role in a sipXecs domain. For example, since the min and max properties for the Management role is set to 1, there must exist one and only one Management role in a domain. Likewise, one can infer that the Redundant SIP Router is optional, and no more than two can exist in a domain.

Services

A Role requires one or more services to be configured and running. For example, the Voicemail role requires the "Voicemail and Auto Attendant", "Media Services", and "Voicemail MWI" services to be running. One service might be required by multiple roles. For example, "Media Services" is required by both Conferencing and Voicemail roles.
Once a new role has been assigned, the associated service will be started automatically if not already running. Likewise, if a role has been unassigned, services no longer required will be stopped.
Services can be started, stopped or restarted manually in System>Server>Services screen. In the same screen, each service's configuration screens can be accessed.

Service Definition

Services are defined in the file sipXconfig/neoconf/src/org/sipfoundry/sipxconfig/service/service.beans.xml. Each service is described as a bean and each service bean is a child of the abstract sipxService bean. The abstract service bean sipxService defines properties relevant to all services and its corresponding java class is SipxService. Likewise, each concrete service bean has a corresponding java classe which reflects the bean hierarchy. For example, the sipxSupervisorService bean is derived from the abstract sipxService bean, and the corresponding SipxSupervisorService bean class is derived from the abstract SipxService class.
The SipxService class is pivotal because it ties the service to its setting model and and the Hibernate ORM by extending BeanWitFurthermore, it implements the ServiceLifeCycle interface to allow all SipxService subclasses to customize and control their own life cycle behavior.
The service bean xml also defines the service manager bean (sipxServiceManagerImpl) and the class (SipxServiceManagerImpl) which manages the services and the association to the bundles.
Each service bean has a "bundles" property which is a list of bundles (roles) which depend on the service. For example, the sipxProxyService is required by both primary and secondary SIP Router bundles:

<property name="bundles">
<set>
<ref bean="primarySipRouterBundle" />
<ref bean="redundantSipRouterBundle" />
</set>
</property>

The service beans xml contains information on the services' associated process name, model files, configurations and dependent bundles. The modeling files contain setting descriptions and these drive the configuration parameters as well as GUI screens for each service. On the System>Server>Services screen, each service have a link to its configuration screen. The configuration screen will allow the users to update any configurable parameters described in the model file.

<bean id="sipxProxyService" class="org.sipfoundry.sipxconfig.service.SipxProxyService" parent="sipxService"
scope="prototype">
<property name="processName" value="SIPXProxy" />
<property name="modelName" value="sipxproxy.xml" />
<property name="modelDir" value="sipxproxy" />
<property name="editable" value="true" />
<property name="configurations">
<list>
<ref bean="sipxProxyConfiguration" />
<ref bean="peerIdentitiesConfiguration" />
</list>
</property>
<property name="bundles">
<set>
<ref bean="primarySipRouterBundle" />
<ref bean="redundantSipRouterBundle" />
</set>
</property>
</bean>

Service beans can be described in its own bean xml file. For example, the sipxOpenfireService bean is described in sipxOpenfire-service-models.beans.xml. However, the bean is derived from sipxService, and defines the same properties as the other service beans. More specifically, the property "bundles" is also configured to identify the set of bundles (imBundle) which requires the service.

Service Bean Properties

The table below shows the major set of properties in the service.beans.xml and how each property is used by sipXecs.

Service Configuration Properties

Each service has related configuration files. The configuration files are described within the _service.beans.xml_ file as configuration file beans and referenced in the service bean definition.
For the configuration files defined within the services bean xml, the files are either XML files or velocity template generated files. Note that velocity templates can generate files of any format, including XML files. The majority of the configuration file beans are derived from the ServiceConfigurationFile bean, which has SipxServiceConfigurationFile as the bean class. SipxServiceConfigurationFile extends TemplateConfigurationFile, thus provides the velocity template capabilities. The remaining configuration file beans' bean classes are derived from the java class XmlFile, which provides the XML document capabilities. Configurations, which are velocity based, will setup its velocity context by overriding setupContext while configurations which are XML based will set up its XML document by overriding getDocument.
All configuration file bean classes are children of AbstractConfigurationFile.
The table below shows the major set of properties in the service.beans.xml which are related to service configuration files.

Roles and Services Associations

The table below shows the associated services for each role. For the "Required Service" column, services which are required by only one role is shown in bold. Services required by more than one role (shared) are in italic, except for services shared between the Primary and Secondary SIP Routers, which are in normal font.

The labels in the "Role" and "Required Service" columns are as seen on the System>Servers>Services GUI screen and configured in the sipXconfig-web.properties file. The Bean Id column is the SipxService bean which is defined in the service.bean.xml file. The "Process Name" column is from the "processName" property of each SipxService definition. The last column "Process/Class" shows either the Linux executable (in lower case), the java class to be loaded (fully qualified java class name), or a ruby mainline entry point.

Process

Each service bean definition contains a processName property which defines the name of the process associated with the service. When a service is to be started, stopped or restarted, SipxProcessContextImpl class retrieves the process name from the SipxService instance so that the correct process can be managed on the host. At the same time, SipxProcessContextImpl will ask AuditLogContextImpl to write an audit log into sipxconfig.log using the processName. Similarly, ConfigVersionManagerImpl uses the processName to uniquely identifies the process when setting the config version of the process.
All process description xml files are installed in sipxecs/process.d/. There are total of 23, one for each service, except for the sipxAlarmService which shares the sipxsupervisor process. The name element of each file corresponds to the processName in the service.bean.xml. This is how a SipxService is correlated with its process.
For example, the xml snippet below is from the file share/sipxecs/process.d/freeswitch-process.xml. The name element "FreeSWITCH" correlates with the property value "FreeSWITCH" for the sipxFreeswitchService bean in service.beans.xml file.

<?xml version='1.0' encoding='iso-8859-1' standalone='yes'?>
<sipXecs-process xmlns='http://www.sipfoundry.org/sipX/schema/xml/sipXecs-process-01-00'>
<name>FreeSWITCH</name>
<version>4.3.0</version>
<commands>
<configtest>
<execute>/home/carson/scs3/INSTALL/bin/freeswitch.sh</execute>
<parameter>--configtest</parameter>
</configtest>
<start>
<execute>/home/carson/scs3/INSTALL/bin/freeswitch.sh</execute>
</start>
<stop>
<execute>/home/carson/scs3/INSTALL/bin/freeswitch.sh</execute>
<parameter>--stop</parameter>
</stop>
</commands>

ConfigureBundlesPanel

This class handles the role assignment validation when updating the role assignment. This will start a chain of invocations which will:

• validate the new bundle assignment against bundle properties - see SipxServiceManagerImpl.setBundlesForLocation() where filter() validates the onlyPrimary and onlyRemote properties and verifyBundleCardinality() verifies the max/min properties against the cluster - see SipxServiceManagerImpl.setBundlesForLocation()'s filter() and verifyBundleCardinality().
• prepare the services for restart/stoppage by calling the LifeCycle methods. For service to be started, the onInit() is called, for services to be stopped, the onDestroy() will be called. - see Location.resetBundles()
• stopping services no longer required -see SipxProcessContextImpl.manageServices()
• replicate service configuration files - see serviceConfigurator.enforceRole()

Log Files

As mentioned previously, the service definition in the service.bean.xml file contains the processName property. This property is outputted to the sipxconfig.log file to trace service process activations. For example, if you assign the Voicemail role on a server, you will see an auditlog similar to below:

auditlog:"Replicated freeswitch.xml to bcmsl2072.ca.nortel.com"
auditlog:"Started FreeSWITCH  on bcmsl2072.ca.nortel.com"
auditlog:"Started SIPStatus  on bcmsl2072.ca.nortel.com"
auditlog:"Started sipXivr  on bcmsl2072.ca.nortel.com"

where sipXivr, SIPStatus, and FreeSWITCH are all process names of SipxService defined the service.beans.xml file to be a required service for the Voicemail role.

Display String Properties

Bundles and services are show in the GUI with names that do not match the source code (e.g. java classes and xml files). These GUI names are show in the System>Server>Server Roles and System>Server>Services sipXconfig screens. The GUI names are set in the sipXconfig web applicaton properties file sipXconfig-web.properties and can help to correlate with the bundle and services defined in bundle.beans.xml and service.beans.xml. The relevant bundle and service GUI label are shown below:

bundle.management=Management
bundle.primarySipRouter=Primary SIP Router
bundle.redundantSipRouter=Redundant SIP Router
bundle.voicemail=Voicemail
bundle.conference=Conferencing
bundle.borderController=SIP Trunking
bundle.acd=ACD
bundle.im=Instant Messaging

label.sipxAcdService=ACD
label.sipxBridgeService=SIP Trunking
label.sipxCallResolverService=CDR
label.sipxCallResolverAgentService=CDR HA Tunnel
label.sipxConfigService=Configuration
label.sipxConfigAgentService=ACD Statistics
label.sipxFreeswitchService=Media Services
label.sipxImbotService=MyBuddy
label.sipxIvrService=Voicemail and Auto Attendant
label.sipxMrtgService=Statistics
label.sipxParkService=Park
label.sipxPageService=Paging
label.sipxPresenceService=ACD Agent Status
label.sipxProxyService=SIP Proxy
label.sipxRecordingService=Conference Recording
label.sipxRelayService=Media Relay
label.sipxRegistrarService=SIP Registrar
label.sipxRlsService=Presence
label.sipxSaaService=Shared Appearance Agent
label.sipxStatusService=Voicemail MWI
label.sipxSupervisorService=Supervisor
label.sipxOpenfireService=Instant Messaging
label.sipxRestService=Call Control
label.sipxProvisionService=Phone Provisioning