1. Role Utility


The WIN-911 Role Utility is a console application that can modify or query Roles associated with a WIN-911 Connection. Execution of the utility may be scripted through your SCADA/HMI project, allowing operators to affect Role changes in WIN-911 without ever leaving the HMI. When combined with the role-based notification of Advanced Tactics, operators can even control who will receive notifications.


NOTEAdvanced Tactics require an Advanced license.


A. Install Location 


The Role Utility consists of two components which are installed with the Dispatcher module, an executable and its corresponding configuration file.


EXE

C:\Program Files (x86)\WIN-911 Software\WIN-911 Enterprise\Dispatcher\Roleutility.exe


Config

C:\Program Files (x86)\WIN-911 Software\WIN-911 Enterprise\Dispatcher\Roleutility.exe.config

A.1 Syntax 


roleutility.exe cmd={add|remove|removeall|query} notifier={email|sms|voice|mobile|mobile911} connectionid=<Connection ID> roleid=<Role ID>


A.2 Arguments 


cmd=add

Adds a Role to a Connection.


cmd=remove

Removes a Role from a Connection.


cmd=removeall

Removes all Roles from a Connection.


cmd=query

Returns all Roles assigned to a Connection.


notifier

Specify the Notifier the Connection belongs to (email, SMS, voice, or mobile911).


connectionid

Specify the Connection ID to modify (Must be a GUID). Connection IDs are located Connection IDs respective notifier SQL database. (See WIN-911 Connection GUIDs section below)


roleid

Specify the Role ID to add or remove from a Connection (Must be a GUID). Role IDs are located in the Dispatcher SQL database table, RoleEntities. (See WIN-911 Role GUIDs section below)


A.3 Examples


NOTEIn the following examples, we are using randomly generated GUIDs. When you run the utility, you must use the GUIDs from your WIN-911 databases. Failing to do so will lead to configuration issues.


Add a Role to an Email Connection

roleutility.exe cmd=add notifier=email connectionid=974a8c2c-01e3-4aab-9955-3c8d4613eb15 roleid=54194883-f98f-4387-9af6-abbeef761aa51aa5


Remove Single Role from an Email Connection

roleutility.exe cmd=remove notifier=email connectionid=974a8c2c-01e3-4aab-9955-3c8d4613eb15 roleid=54194883-f98f-4387-9af6-abbeef761aa5


Remove All Roles from an Voice Connection

roleutility.exe cmd=removeall notifier=voice connectionid=974a8c2c-01e3-4aab-9955-3c8d4613eb15


Query Roles on an Email Connection

roleutility.exe cmd=query notifier=email connectionid=974a8c2c-01e3-4aab-9955-3c8d4613eb15



B. Where to Find GUIDs


The GUID (globally unique identifier) for a WIN-911 Connection and optional WIN-911 Role must be provided when running the Role Utility. GUIDs for both Roles and Connections can be found in the WIN-911 configuration databases stored in MS SQL Server. The directions below will walkthrough locating GUIDs for Roles and Connections using MS SQL Server Management Studio. 


NOTEBefore you can locate the GUIDs in your SQL databases, you must first create the Roles and Connections that you plan to use with WIN-911 Workspaces. 



C. Accessing SQL Server

During the installation of WIN-911, the installer offered to install a local instance of SQL Server Express with SQL Server Management Studio. If selected, an SQL instance named "WIN911" was created on the WIN-911 PC. If not selected, an SQL instance was manually entered. The SQL instance targeted by WIN-911 can be identified by launching WIN-911 Workspace and navigating to System / Info.


If the WIN-911 installer was used to install SQL Server, only the Windows user account used during installation has sysadmin permissions. The credentials of this account will be needed to login to the "WIN911" instance.


  • Launch MS SQL Server Management Studio using a Windows account with access to the SQL instance. 
    • If you are not sure which account to login with, open Windows Services, locate one of the WIN-911 services, the Windows account listed under the Log On As column can be used.
  • After MS SQL Server Studio has launched, connect to the SQL Instance where your WIN-911 databases are located. 
    • Again, if the WIN-911 Installer installed SQL Server Express for you, you will use <SERVERNAME>\WIN911



D. WIN-911 Role GUIDs


Roles are configured in the Dispatcher module, as such, their GUIDs are located in the Dispatcher's database.

  • Using the Object Explorer in SQL Management Studio, expand WIN-911 Instance, Databases,  ComputerName-911.Default.Dispatcher, and Tables.
  • Locate and right-click the dbo.RoleEntities table and click Select Top 1000 Rows, this query will return a list of the Roles configured in the WIN-911 system.
  • The GUIDs are located in the Id column. 
    • The Name column displays the friendly name of the Role.
    • When specifying the roleid for the Role Utility, use only the GUIDs that appear in this list. 

E. WIN-911 Connection GUIDs


Each WIN-911 Notifier has a database with the following naming convention, ComputerName-911.Default.NotifierName. Within each of these databases exists a table with the Connection IDs needed to run the Role Utility.


Database NameTable Name
ComputerName-911.Default.Emaildbo.EmailConnectionEntities
ComputerName-911.Default.SMSdbo.SmsConnectionEntities
ComputerName-911.Default.Voicedbo.VoiceConnectionEntities
ComputerName-911.Default.Mobile911dbo.Mobile911ConnectionEntities


For the purpose of this document, we'll use the Mobile-911 Notifier as an example.

  • Using the Object Explorer in SQL Management Studio, expand WIN-911 Instance, Databases,  ComputerName-911.Default.Mobile911, and Tables.
  • Locate and right-click the dbo.Mobile911ConnectionEntities table and click "Select Top 1000 Rows", this query will return a list of the Mobile-911 Connections configured in the WIN-911 system.
  • The GUIDs are located in the Id column. 
    • The Name column displays the friendly name of the Connection.
    • When specifying a connectionid for the Role Utility, use only the GUIDs that appear in the Notifier tables

F. Utility Configuration File


The Role Utility's configuration file, RoleUtility.exe.config, contains two pieces of information that are required for successful communication with the SQL Instance the utility is targeting, the SQL connection string and WIN-911 System Name. You may need to modify this information if the SQL instance you are using changes, or you are targeting multiple WIN-911 systems from one PC. For example, if you are running a WIN-911 Hot Backup and you'd like to make changes to both systems, you will need to make a copy of the utility exe and config file and place the copies in a separate folder. One utilities' config would point to the primary WIN-911 while the other config would point to the backup.


NOTE: The configuration file is a plain text file, you can use Notepad for edits.


F.1 Connection String


When the utility is installed, the connection string is created by the installer and it points to the SQL instance specified during installation. If you need to target a different SQL instance, you will need to update the Server value with the new instance name. 

Default Connection String

<connectionStrings>
<add name="RoleUtilityDataContext" providerName="System.Data.SqlClient" connectionString="Server=ServerName\WIN911;Database=;Integrated Security=True;MultipleActiveResultSets=true" />
</connectionStrings>


The Connection String also specifies the authentication that will be used when communicating with the SQL instance. The default string specifies Windows Authentication, meaning, the Windows user account running the utility will be used to authenticate with the SQL instance. If you find this problem while scripting the utility in your HMI application, you can modify the Connection String to contain login credentials for the SQL Instance. You will need to create a local SQL user in your SQL instance and ensure they have read/write privileges. 


Remove the Integrated Security parameter and replace it with the User Id and Password parameters.


Connection String with User ID and Password

<connectionStrings>
<add name="RoleUtilityDataContext" providerName="System.Data.SqlClient" connectionString="Server=ServerName\WIN911;Database=;User Id=myUsername;Password=myPassword;MultipleActiveResultSets=true" />
</connectionStrings>


F. 2 WIN-911 System Name


The configuration file also targets the WIN-911 System Name, which is the name of the server running WIN-911 appended with -911. E.g. ServerName-911 If you are targeting a different WIN-911 system, you must update this property in the config file.


 <add key="System" value="ServerName-911" />


Technical Support


To create a support case, you will need either your Maintenance Support number or your CD Tracking number. You can create a Case online or contact the product support line: (512)326-1011.