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.
-
Copy an existing role file and rename it appropriately. The supplied files are located in $MSTATION_HOME/mserver/webapps/mserver/config/roles.
-
Open the new file in a text editor.
-
Change the <name> element to identify the new role in the Management Station. Optionally, change the <description> element to describe the new role.
-
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.
-
Modify that instance according to its function (for example, change the instance name, modify the service type, increment port numbers, and so on).
-
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.
-
Assign the new role to a host in Management Station.
-
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:
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.
-
Make a copy of the role file that runs 25 instances to use it as a model for your new role file.
-
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>
-
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).
-
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>
-
Save the role file with a new, meaningful name (for example, 30KRYPTON.xml) and place it in the $NUANCE_DATA_DIR/system/customRoles directory.