Configuring services with role files

When you set up a Nuance network (see How to create the network), you use predefined configurations called roles to assign services to hosts. A role file defines the role and its associated services. You can create your own roles in custom role files if default role files available in Management Station do not meet your deployment needs. For example, to run more service instances than allowed by the provided roles, you could create your own role.

Tip: Another option is to add services to an existing host configuration in the Network Design view of Management Station. See Creating custom roles.

How to create a role file

Creating a new role, no matter what its intended function, typically involves the steps described below. A description of the basic structure of a role file follows.

  1. Copy an existing role file and rename it appropriately. The supplied files are located in $MSTATION_HOME/mserver/webapps/mserver/config/roles.

  2. Open the new file in a text editor.

  3. Change the <name> element to identify the new role in the Management Station. Optionally, change the <description> element to describe the new role.

  4. Make changes as necessary. For example, add new services or create additional instances of the desired service to handle the new functionality.

    Note that the services with multiple instances may have different property values from subsequent instances. Additionally, each instance needs to increment several properties by standard amounts. Therefore, when creating new instances, it is recommended to create the newest instance from a copy of the last instance in the role file. Then, configure the new instance as described next.

  5. Modify that instance according to its function (for example, change the instance name, modify the service type, increment port numbers, and so on).

  6. Place the new role file in the $NUANCE_DATA_DIR/system/customRoles directory. (You must have write access to this location.) You’ll notice that the role file DTD has been copied here. This file is required.

  7. Assign the new role to a host in Management Station.

  8. Finish configuring the service at the desired scope on the service properties tabs. See Setting service properties for more information on configuring specific services.

How to organize the role file structure

Each role included with Management Station is based on an XML configuration file, which is divided into two major sections:

  • Prolog: Identifies the XML version and the DTD (Document Type Definition) to describe and validate the XML data
  • Body: Defines the role and services comprising the role

The role file DTD is located in $MSTATION_HOME/mserver/webapps/mserver/config/roles/role-1-0.dtd.

Prolog

The prolog looks like this:

<?xml version="1.0"?>
<!DOCTYPE role PUBLIC '-//Nuance/DTD NVP Role 1.0//EN' 'role-1-0.dtd'>

Body

The body consists of elements arranged in a hierarchical structure:

<!-- Defines the role version and names the role -->
<role version="1.0">
  <name>...</name>
  <description>...</description>
 
<!-- Defines the service types and instances comprising the role -->
  <services>
    <service type=...>
      <instance...>
        <command>
        <!-- Specifies the command line to start the instance -->
        </command>
      </instance> 
      <!-- Specifies additional instances if required -->
      <instance>
      ...
      </instance>
    </service> 
    <service type=...>
    ...
    </service>
    ...
  </services>
</role>

In creating your own role, you can just make a copy of one of the XML files, rename it, then modify it as necessary. When done, move the file to $NUANCE_DATA_DIR/system/customRoles.

Configurable elements

The elements in the Body section that you may modify include:

This element defines the name of the role to appear in the configuration role list. For example:

<name>Nuance Speech Server</name>

This optional element provides a description of the role. For example:

<description>This role defines a host to run the Nuance Speech Server...</description>

This element delimits the section where the service types and service instances are defined. For example, the Nuance Speech Server looks like this:

<services>
  ...
  <service type="nss">
    <description>
      Nuance Speech Server
    </description> 
    <instance name="Nuance Speech Server" starttype="automatic" startorder="4">
      <command>
        <!-- Specifies the command line to start the instance. -->        
      </command>
    </instance>
  </service>
  ...
</services>

The service type attribute identifies the service; for example, "nss" for Nuance Speech Server, "fts" for file transfer service, and so on. The value must be a valid type specified by the system. Case matters as well: "NSS" is not the same as "nss". Valid values are:

  • fts—For the file transfer service
  • krypton—For the Krypton service
  • nle—For the Natural Language Engine
  • nlps—For the Natural Language Processing service
  • nrm—For the Nuance Resource Manager
  • nss—For the Nuance Speech Server
  • ntpe—For the Nuance Text Processing Engine
  • nvs—For the Nuance vocalizer service
  • rs—For the Nuance recognition service
  • sc—For the statistics collector service

Each <service> element contains one or more service instances. The attributes specify the service instance name, the startup type, and the start order.

  • The value of the name attribute is what Management Station displays, for example, File Transfer, Nuance Speech Server, or Krypton 3 (to specify the correct instance number).

    Note: Service instance names must contain only valid characters. These are +-_() and alphanumeric characters. If the role contains invalid service instance names, you will not be able to assign it to a physical host.

  • The starttype attribute is one of three values: automatic, manual, or disabled. See General tab for more information.
  • Each service instance has a number indicating its start order. Management Station starts the service with lowest number first, followed by the one with the next higher number and so on. The order is determined by dependencies. If service Y starts before service X, then Y must have a lower start order than X. The sequence doesn’t have to start at zero or even be consecutive. The only requirement is that the values must range from low to high.

    Always start instances of the same service type in the same start order. (Services of different types can start in any order as long as there are no service dependencies.) See Starting and stopping services for more information.

This element specifies the command and default service properties that affect startup and performance.

These optional elements customize the behavior of services. Typically, you only change port properties: each service instance requires an incremented port number (usually incremented by 10). For example, the default port for Krypton is 8600, the second Krypton instance uses port 8610, the third uses 8620, and so on. Ensure no port conflicts occur.

Example

Imagine that you want to create a role file that runs 30 instances of Krypton. Management Station provides several role files that run multiple instances of Krypton as a standalone service: a single instance, 10 instances, 25, 50, 75, and 100 instances.

To create a role file that supports 30 instances of Krypton, base your new role file on the role file that supports 50 instances and remove the last 20, or use the role file that supports 25 and add five additional instances. The latter strategy is described in detail below.

  1. Make a copy of the role file that runs 25 instances to use it as a model for your new role file.

  2. In the new file, change the <name> and <description> elements to identify the new role in the Management Station. For example:

    <?xml version="1.0"?>
<!DOCTYPE role PUBLIC '-//Nuance/DTD NVP Role 1.0//EN' 'role-1-0.dtd'>
<role version="1.0">
    <name>30 KRYPTON</name>
    <description>
            This role defines a host that runs 30 instances of the Krypton engine.
    </description>    
    <services>
        <service type="krypton">
            <description>Krypton.</description>
            ...
        <service>    
    </services>
</role>

  3. Add the additional five instances to the bottom of the <service> section using the last <instance> element in the role file as a model (copy and paste five times).

  4. Modify each new instance to increment the instance number and port number. For example:

            <service type="krypton">
            <description>Krypton.</description>
            ...
            <instance name="Krypton 25" starttype="automatic" startorder="3">
                <command>
                    -pa %KR_HOME%/bin/krypton
                </command>
                <properties group="configparams" type="krypton">
                    <property><name>https : port</name><value>8840</value></property>       
                </properties>
            </instance>
            <instance name="Krypton 26" starttype="automatic" startorder="3">
                <command>
                    -pa %KR_HOME%/bin/krypton
                </command>
                <properties group="configparams" type="krypton">
                    <property><name>https : port</name><value>8850</value></property>       
                </properties>
            </instance>
            ...
            <instance name="Krypton 30" starttype="automatic" startorder="3">
                <command>
                    -pa %KR_HOME%/bin/krypton
                </command>
                <properties group="configparams" type="krypton">
                    <property><name>https : port</name><value>8890</value></property>       
                </properties>
            </instance>
        <service>

  5. Save the role file with a new, meaningful name (for example, 30KRYPTON.xml) and place it in the $NUANCE_DATA_DIR/system/customRoles directory.