Discover Technical Guide. Applicable to onwards

Transcription

1 Discover Technical Guide Applicable to onwards

2 Revision History Version Change Description Date Handbook restructured to clarify processes. 24/07/ Rebranding of front cover. 25/07/ References to SupportNet have been changed to My Account throughout the document. 08/07/ Enabling Roles and Features in Windows 2016 Server Manager topic added to Additional Setups and Troubleshooting chapter. 19/06/2017 Capita Business Services Ltd All rights reserved. No part of this publication may be reproduced, photocopied, stored on a retrieval system, translated or transmitted without the express written consent of the publisher. Microsoft and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Capita Doc Ref: DiscTechGuide7158/HBK/190617/FT Providing Feedback on Documentation We always welcome comments and feedback on the quality of our documentation including online help files and handbooks. If you have any comments, feedback or suggestions regarding the module help file, this handbook (PDF file) or any other aspect of our documentation, please publications@capita.co.uk Please ensure that you include the module name, version and aspect of documentation on which you are commenting. Capita SIMS, Franklin Court, Priory Business Park, Cardington, Bedfordshire MK44 3JZ Tel: Fax: info@capita-sims.co.uk Web:

3 C Contents 01 Introduction to Discover in Advanced Installation Mode 1 Introduction... 1 Where to Find More Information... 1 Prerequisites for Using Discover... 2 Target Operating Systems... 3 Planning for the Installation... 3 What s New in this Release?... 3 Improvements to the Group Synchronisation Procedure Installing Discover in Advanced Mode... 5 Introduction... 5 Overview of Discover as an XBAP Application... 5 Discover Advanced Installation Process Flow Diagram... 7 Discover Upgrade Process Flow Diagram... 8 Installing Discover Databases... 9 Deploying Additional Discover Databases Generating a Catalogue for Each Database Creating Domain User Accounts Recommendations for Creating Domain Users Web Service Account Installing Discover Services The SIMS Discover Data Transfer Service The SIMS Discover Group Synchronisation Service The Discover User Synchronisation Task The Discover Data Transfer Scheduled Task Granting Database Access to Service Accounts Putting the Services into Hosted Mode Synchronising SIMS Users Installing the Discover Shared Session Store Installing the Discover Web Services User Principal Name Format Login Granting Database Access to the Application Pool Account Enabling Request Routing for the Web Services Editing the Web.Config File to Enable Routing The Regular Expression Router Using the Active Directory or LDAP Router Writing Your Own Custom Router Transferring Data from SIMS to the Discover Database(s)... 30

4 Permissions Required to Access the Discover Administration Utility for Hosted Installations Considerations when using the Browser Client Considerations when using the Desktop Client Configuring Scheduled Discover Transfers Installing the Discover Desktop Clients Enabling the Browsers for the XBAP Application Installing the Public Certificate on a Client Machine Additional Setups and Troubleshooting Amending the Hosted Settings File to Reflect the SIMS and Discover Database Names Modifying the Service Application Settings Using the Discover Log Viewer Utility Recovering from a Partial Server Failure on a Hosted Installation 45 Enabling Roles and Features in Windows 2016 Server Manager Index... 49

5 01 Introduction to Discover in Advanced Installation Mode 01 Introduction to Discover in Advanced Installation Mode Introduction Introduction... 1 Where to Find More Information... 1 Prerequisites for Using Discover... 2 Planning for the Installation... 3 What s New in this Release?... 3 This handbook concentrates primarily on achieving a successful Advanced Installation of Discover. It also contains more detailed information about a number of essential Discover components and how these can be modified to accommodate your specific configuration. The Discover application makes extensive use of modern graphics technology, Windows Presentation Foundation (WPF), in order to present an intuitive interface for data analysis. In turn, WPF makes extensive use of a modern Graphics Processing Unit (GPU). However, this can pose challenges when running Discover in hosted environments such as Citrix and Terminal Services because running multiple instances of Discover within these environments can place a disproportionate burden on the servers and cause lag in low bandwidth WAN situations. While it is possible to deploy Discover in its usual client/server configuration in such environments, the installation of Discover includes special support to assist in mitigating these problems. You can use SOLUS 3 to automate the deployment of Discover, as this also takes care of prerequisite deployment, installation ordering and future upgrades. However, the Discover installation files are contained in the ISO.zip file and this can be downloaded from the My Account website ( Where to Find More Information Online help can be accessed by pressing F1 or clicking the applicable Help button in SIMS. A wide range of documentation is available from the SIMS Documentation Centre, including handbooks, quick reference sheets and tutorials. Click the Documentation button (located on the top right-hand side of the SIMS Home Page), select the required category and then select the document you require. Alternatively, use the Search facility to locate the required document. Documentation is also available from the My Account website ( Discover Technical Guide 1

6 01 Introduction to Discover in Advanced Installation Mode 1. Enter the required text in the Search field to display a list of documents that match the search criteria. 2. To refine the search further, click Documents and then select the required Document type, File type and/or Date range (click Show more to view additional options, if required). Alternatively, click SIMS Publications (located in the Popular Searches list) to display a list of all SIMS publications. The search results are displayed automatically. Tips for using the My Account Search Facility Here are some key tips for using the search facility in My Account. For additional explanations, please refer to the My Account website. The search results can be refined further by using the advanced filters, e.g. Sort by relevance or Sort by last modified. The following rules can be applied to your search terms: Surround a word or phrase with "double quotes" to return results containing that exact phrase. Prefix a words or phrases with + to make them essential. For example: end of year procedures +primary +detailed Prerequisites for Using Discover Before installing Discover, it is suggested that you identify a suitable machine in your establishment with the highest possible specification and ensure that the following applications, devices and drivers are installed: SIMS 2014 Summer Release with a SIMS database. SQL Server Microsoft.NET Framework version 4.0. SIMS already contains the necessary components of Microsoft.NET Framework version 2.0 that are utilised by Discover. A CPU with a Core Duo 2 or a higher specification processor. A dedicated graphics card with appropriate drivers installed (for client machines only). NOTE: It is suggested that a GPU with an integrated chipset is not used to run Discover. At least 4GB of memory. The Discover database requires at least 50MB space on the server where it resides. The Discover Transaction log requires at least 100MB space on the server where it resides. IMPORTANT NOTE: The person carrying out the installation of SIMS Discover must have Administrator permissions over the network. 2 Discover Technical Guide

7 01 Introduction to Discover in Advanced Installation Mode Target Operating Systems The following operating systems are recommended for use with Discover to ensure satisfactory performance and optimal graphical display in both 32-bit and 64-bit versions: Windows XP SP3 or later Windows Vista Windows 7 Windows Server 2008 SP2 or later Windows Server 2008 R2 Windows Server 2012 or later (when using Discover Web Services only). NOTE: When using Discover with a Touch Screen, Windows 7 must be used because Windows XP does not have Touch Screen capabilities. Planning for the Installation IMPORTANT NOTE: It is strongly suggested that you read through this guide and decide on the best approach for installing Discover as a hosted application on your own server setup, before you begin. Due to varying server setups, web farm and server specifications, you may need to consider different aspects or methods for achieving the desired result. What s New in this Release? A number of additional features and enhancements have been provided in this release including: Improvements to the Group Synchronisation Procedure Improvements have been made to the SIMS Discover Group Synchronisation Service to enhance performance when hosting multiple databases on a server. More Information: The SIMS Discover Group Synchronisation Service on page 16 Amending the Hosted Settings File to Reflect the SIMS and Discover Database Names on page 39 Discover Technical Guide 3

8 01 Introduction to Discover in Advanced Installation Mode 4 Discover Technical Guide

9 02 Installing Discover in Advanced Mode Introduction Introduction... 5 Overview of Discover as an XBAP Application... 5 Discover Advanced Installation Process Flow Diagram... 7 Installing Discover Databases... 9 Generating a Catalogue for Each Database Creating Domain User Accounts Installing Discover Services Granting Database Access to Service Accounts Putting the Services into Hosted Mode Synchronising SIMS Users Installing the Discover Shared Session Store Installing the Discover Web Services Granting Database Access to the Application Pool Account Enabling Request Routing for the Web Services Transferring Data from SIMS to the Discover Database(s) Installing the Discover Desktop Clients Enabling the Browsers for the XBAP Application Before beginning the installation, we strongly suggest that you spend some time familiarising yourself with the Discover components and understanding how these can best be deployed on your specific configuration. Overview of Discover as an XBAP Application In order to move the resources required for producing and displaying complex graphics away from the server and the Terminal Services or Citrix environment, the Discover client can be run within a Web browser. This is accomplished via the deployment of a Web server layer that includes Web services and a WPF Browser Application wrapped within an XBAP package. IMPORTANT NOTE: An installation of Microsoft.NET 4 Framework is still required on the client machine that is running the Web browser. It is not possible to run Discover on an Apple Mac or a Linux machine. Discover Technical Guide 5

10 This approach is suitable for schools and Local Authorities that run hosting technologies such as Terminal Services and Citrix and who want to host the Discover database on a separate SQL Server instance from the normal SIMS installation. The Discover client can be accessed via a URL endpoint at which time the client is downloaded and deployed directly into the Web browser. The users can log into Discover using their usual SIMS user names and passwords. IMPORTANT NOTE: It is strongly suggested that you read through this guide and decide on the best approach for installing Discover as a hosted application on your own server setup, before you begin. Due to varying server setups, web farm and server specifications, you may need to consider different aspects or methods for achieving the desired result. 6 Discover Technical Guide

11 Discover Advanced Installation Process Flow Diagram The following flow diagram can be used as a point of reference when you are installing Discover. Key to Colours Used Blue = step from the installation wizard Yellow = requires a decision Grey = manual step. Discover Technical Guide 7

12 Each of the activities detailed in the flow diagram are explained in more detail in the subsequent sections. Discover Upgrade Process Flow Diagram The following flow diagram can be used as a point of reference when you are upgrading an existing installation of Discover. Key to Colours Used Blue = step from the installation wizard Yellow = requires a decision Grey = manual step. 8 Discover Technical Guide

13 Each of the activities detailed in the flow diagram are explained in more detail in the subsequent sections. Installing Discover Databases The Discover application is required to process large amounts of data to enable the creation of graphical displays for analysis. Instead of continually requesting this data from the SIMS database, and to enable this data to be available when required, the data is periodically transferred to a separate Discover database. It is essential that every SIMS database is paired with a dedicated Discover database so that this transfer of data can occur. Before installing a Discover database using the Advanced Installation method, you must consider whether your users will be accessing Discover from the desktop client or the browser client (XBAP), and whether your users will be logging in with SIMS logins or Windows logins. The outcome of these considerations will affect the final location of the Discover database in terms of SQL Server instances. If you opt to access Discover from the desktop client, all of your users must have their SQL Server login attached as a user to the Discover database with the appropriate rights granted. The Discover User Synchronisation Task, installed with the Discover Services, ensures that the users of the Discover database match those who currently access the SIMS database. NOTE: However, SIMS logins cannot be transferred between different SQL Server instances. If the desktop client is used with SIMS logins, the Discover database must be installed on the same SQL Server instance as the SIMS database it is paired with. If Windows logins are used or the browser client is deployed, the SIMS and Discover databases can exist on separate SQL Server instances. Discover Technical Guide 9

14 A Discover database can either be installed using the Discover installation wizard or from the command line. Details of command line parameters can be found in the Installing Discover Databases section of the Discover Command Line Installation of Discover Components guide. Select the appropriate radio button to determine the Authentication method to use. This defines how the wizard will connect to the SQL Server to undertake the installation/upgrade process. It does not determine the authentication method used by the service. To install a Discover database, you must provide the following minimum details: the name of a SQL Server instance at SQL Server version 2012 or later that will host the database a unique name for the Discover database. Deploying Additional Discover Databases If you host multiple schools on one server, the Install Discover Database option must be run once for each individual school. This enables you to create a site specific Discover database for each school. It is suggested that you use the naming convention of Discover_SchoolA, Discover_SchoolB, etc. so that you can clearly discern the difference between a Discover and a SIMS database for each hosted school site. Discover has the ability to store data from previous academic years. This is presently restricted to three academic years, the current year, last year and two years ago. Each year is stored as a separate set of data in the Discover database, so you must ensure that you have sufficient storage capacity available to allow for the additional years of data. 10 Discover Technical Guide

15 The size of a Discover database depends on a variety of factors including the amount of data in the paired SIMS database, the number of years of academic data that has been transferred, how many months of the current academic year have passed and the number and type of graphs that have been created in the Discover Administration Utility. Therefore, if you are hosting multiple schools, it is recommended that you deploy a few schools initially so that you can gauge the resources that will be required. Generating a Catalogue for Each Database The catalogue generation tool inserts the pre-defined graph definitions, provided by Capita SIMS, into the Discover database. You must carry out this process from the command line and if you are hosting multiple databases, this must be done on each Discover database. Please refer to Generating a Discover Catalogue in the Discover Command Line Installation guide. Creating Domain User Accounts Discover is typically installed using built-in accounts for its Windows Services and in most cases, this is acceptable. However, there are some advantages to using specifically created Domain user accounts instead: The accounts can be assigned only sufficient rights to access the SIMS and Discover databases in accordance with the security principle of least privilege. If you create a number of accounts, this reduces contention for resources, thereby improving performance. Recommendations for Creating Domain Users Hosted Discover requires the creation of two Domain user accounts that are used by its services to access the Discover and SIMS databases. These two user accounts should be created on the Domain Controller in an organisational unit of your choice. You must consider any existing domain policies that could affect these logins and ensure that they will not restrict interaction between the databases and the application server. The Domain user account names and purposes are detailed below: Discover Transfer User This Domain user account is granted access to both the Discover and the SIMS databases. It enables access to the databases for transferring data from the SIMS database into the Discover database by the Discover Transfer Service. Discover Group Synch User This Domain user account is granted access to both the Discover and the SIMS databases. It enables access to the databases for the transfer of Discover Group information from the Discover database into the SIMS database by the Discover Group Synchronisation Service. You should make a note of the actual user names and passwords that have been created for both of these user accounts. They are granted the necessary permissions to run the services during the installation process. Discover Technical Guide 11

16 Once created, the DiscoverGroupSynch user is available in System Manager and automatically assigned rights to the Senior Management Team and System Manager groups. Web Service Account If you are deploying the Discover browser client, you may also want to create a specific Domain account for the Discover Web Services. However, this does not have the same advantages as with the other components because IIS does not handle the default account in the same way as Windows Services. If you apply a specific Domain account to the Discover Web Services, this must be done manually and you must remember to reapply the account to the Web Services application pool after every upgrade. Installing Discover Services The Discover Services comprise two Windows Services that move data between paired SIMS and Discover databases. One instance of the Discover Services can synchronise data between many of these SIMS/Discover database pairs when configured for hosted mode use. The Discover Services can either be installed using the Discover installation wizard or from the command line. Two separate services that are integral to the successful running of Discover are installed, as well as two scheduled tasks. Select the appropriate radio button to determine the Authentication method to use. This defines how the wizard will connect to the SQL Server to undertake the installation/upgrade process. It does not determine the authentication method used by the service. Details of command line parameters can be found in the Installing Discover Components from the Command Line chapter of the Discover Command Line Installation of Discover Components guide. To install the Discover Services you must provide the following details: 12 Discover Technical Guide

17 the name of a Discover database and its SQL Server instance name the name of the paired SIMS database and its SQL Server instance name Discover Technical Guide 13

18 a built-in account or specific Domain account for the SIMS Discover Data Transfer Service a built-in account or specific Domain account for the SIMS Discover Group Synchronisation Service a time when the Discover User Synchronisation Task can be activated 14 Discover Technical Guide

19 a time when the Discover Data Transfer Scheduled Task can be activated, allowing sufficient time for the Discover User Synchronisation Task to complete, preferably a few minutes. an installation directory. Discover Technical Guide 15

20 The SIMS Discover Data Transfer Service This service transfers data between the SIMS and Discover databases, copying data from SIMS to Discover to ensure that the most up-to-date information is available for use in Discover. It is important to recognise that the data Transfer process is always undertaken by the SIMS Discover Data Transfer Service. Scheduled transfers or manual transfers initiated through the Discover Administration Utility simply trigger the SIMS Discover Data Transfer Service to begin the process when it has the capacity to do so. The data Transfer process usually takes between one minute and 30 minutes, depending on the size of the SIMS database. If a maintenance plan exists to update the database statistics and indexes of the SIMS database before a transfer takes place, this has a positive effect on the transfer time. Updating the statistics and indexes of Discover once the transfer has finished has a positive effect on the performance of the Discover client. As the Transfer process runs, a log file is created that records any issues encountered during each run. This log file can become quite large over time, so it is suggested that a maintenance plan is configured on the SQL Server to minimize this log file. To ensure that the data transmitted across your network is secure, it is also suggested that the SQL Server traffic is encrypted. It is also possible to control some of the SQL connection settings. More Information: Modifying the Service Application Settings on page 41 The SIMS Discover Group Synchronisation Service This service synchronises the Discover Dynamic Groups between the SIMS database and the Discover database. This service also enables the group alerts to be sent to group supervisors. Please refer to the Discover User Guide for more detailed information relating to the creation of Discover Groups. The Windows account that this service runs under must be a SIMS account with full permissions and high data access privileges because it requires read access to all data in Discover. This access is created during the installation of Discover. The Discover User Synchronisation Task This task runs a console application called Discover.SQLUserManager.Console.exe, and transfers user information from the SIMS database to its paired Discover database. It should be scheduled to run before the Discover Data Transfer Scheduled Task with sufficient time to complete. The Discover Data Transfer Scheduled Task This task runs a console application called Discover.Warehouse.TriggerConsole.exe, which instructs the SIMS Discover Data Transfer Service to transfer data from a SIMS database to its paired Discover database. The scheduled task only causes data for the current academic year to be transferred, since previous years data does not frequently change. 16 Discover Technical Guide

21 NOTE: It is strongly recommended that transfer routines are not set to run at 12 midnight because pupil/student memberships generally change at this time. Configuring Scheduled Discover Transfers If you have installed Discover using the installation wizards, the Discover Data Transfer Task is created automatically as an integral part of the installation process. This task enables the transfer of data between the SIMS and Discover databases. However, if you have installed Discover from the command line, it is possible to make manual changes to this task by modifying the contents of the Discover.Warehouse.TriggerConsole.exe.config file. This file can be found in the C:\Program Files\SIMS\Discover Services folder. It is possible to specify the DiscoverServerName and DiscoverDatabaseName settings by editing the file using a text editing programme. A parameter can be supplied to the Discover.Warehouse.TriggerConsole.exe, which is accessed when the Scheduled Task is run. Using this parameter, you can create a Scheduled Task to automatically update a previous year's data at a different frequency from the current academic year, e.g. monthly instead of daily. This can be achieved by copying the existing Scheduled Task and adding the new parameter, e.g. /Order="-1" (for Last Year), /Order="-2" (for Two Years Ago). Granting Database Access to Service Accounts The installation of the Discover Services grants the service accounts access to the specified SIMS and Discover databases. If you host multiple databases, access must be granted to additional SIMS and Discover databases for each of the services. Granting database access must be done from the command line. Please refer to the Granting Access Rights to the Data Transfer Service User and Granting Access Rights to the Data View Monitor Service sections in the Command Line Installation of Discover Components guide. Discover Technical Guide 17

22 Putting the Services into Hosted Mode Every SIMS database must be paired with a single Discover database to enable the transfer of data into Discover. However, a single instance of the SIMS Discover Data Transfer Service and one instance of the SIMS Discover Group Synchronisation Service can synchronise data between a number of SIMS/Discover database pairs. To enable hosted mode, the services must be supplied with a list of the database pairs in an XML text file called the Hosted Settings file (hosted.xml). Please refer to Amending the Hosted Settings File to Reflect the SIMS and Discover Database Names for further information about creating and maintaining this file. It is suggested that you stop the SIMS Discover Data Transfer Service and the SIMS Discover Group Synchronisation Service before changing the configuration of these services. You can start and stop the configuration of these services from the Control Panel, by selecting Administrative Tools Services. The SIMS Discover Data Transfer Service This service must be configured to read a Hosted Settings file (hosted.xml) and this can be achieved by placing the file in the Discover Services Installation Directory or by adding a hostedsettingsfile key to the Discover.Warehouse.Service.exe.config file. When hosting multiple databases on a server, it is possible to control the number of data transfer processes that are run simultaneously. Please refer to Amending the Hosted Settings File to Reflect the SIMS and Discover Database Names for further information. The SIMS Discover Group Synchronisation Service This service must be configured to read a Hosted Settings file (hosted.xml) and this can be achieved by placing the file in the Discover Services Installation Directory or by adding a hostedsettingsfile key to the Discover.DataEngine.DataViewMonitor.Service.exe.config file. When hosting multiple databases on a server, it is possible to control the number of data transfer processes that are run simultaneously. Please refer to Amending the Hosted Settings File to Reflect the SIMS and Discover Database Names for further information. Discover User Synchronisation Task This task must be configured to read a Hosted Settings file (hosted.xml) file using the HostedFile parameter. Please refer to Synchronising Discover and SIMS Logins in the Discover Command Line Installation guide. Discover Data Transfer Scheduled Task This task must be configured to read a Hosted Settings file (hosted.xml) and this can be achieved either by placing the file in the Discover Services Installation Directory or by adding a hostedsettingsfile key to the Discover.Warehouse.TriggerConsole.exe.config file. Please refer to Amending the Hosted Settings File to Reflect the SIMS and Discover Database Names for further information. 18 Discover Technical Guide

23 Restart the Discover Services After making any configuration changes, the SIMS Discover Data Transfer Service and the SIMS Discover Group Synchronisation Service must be restarted in order for the configuration changes to take effect because these values are cached to improve performance. You can start and stop the services from the Control Panel, by selecting Administrative Tools Services or by running the Services.Msc. Synchronising SIMS Users When deploying the browser client (XBAP), you do not need to synchronise users between the SIMS and Discover databases because the databases are accessed by the Web Service account on behalf of the authenticated user. When deploying the desktop client, the SIMS and Discover databases are accessed with the user s credentials and so user information must be copied from the SIMS database to its Discover database. When performing a typical installation with a single SIMS database, user synchronisation is performed by the installer, but for advanced installations this process must be performed manually on all SIMS and Discover database pairs. Synchronising SIMS users must be done from the command line. Please refer to the Synchronising Discover and SIMS Logins section in the Command Line Installation of Discover Components guide. Installing the Discover Shared Session Store When deploying the browser client (XBAP), the Discover Web Services must maintain a small amount of session state for the duration of a user s login, e.g. a session ID, their user ID and the database they are connected to. This information is stored in a separate database called the Discover Shared Session Store. This helps to facilitate load balancing and scaling. Only one session store database is required, regardless of the number of instances of the Discover Web Services. The Discover Shared Session Store database can be installed using the Discover installation wizard. Select the appropriate radio button to determine the Authentication method to use. This defines how the wizard will connect to the SQL Server to undertake the installation/upgrade process. It does not determine the authentication method used by the service. Discover Technical Guide 19

24 To install the Discover Shared Session Store database you must provide: the name of the SQL Server instance at SQL Server version 2008 or later that will host the database a unique name for the Discover Shared Session Store database. 20 Discover Technical Guide

25 Installing the Discover Web Services The Discover Web Services installation is comprised of two components that deliver a client to the end user and data to the client. A single instance of the Discover Web Services can route users between many SIMS/Discover database pairs if configured for hosted mode. Multiple instances of the Discover Web Services could be installed behind a load balancer with each configured to route users to their database pair. The Web Services require Windows Server 2012 or later. As the user names and passwords for SIMS and other sensitive information, including pupil/student details, are communicated backwards and forwards between the Web Services and the Discover clients, it is strongly recommended that Secure Sockets Layer (SSL) is in place to secure the Web Services. There is no need to secure the client XBAP download itself. Discover Browser Client (XBAP) The Discover client can be run within a web browser as a WPF browser application. The application is deployed via an XBAP package. You can access it by navigating to the root URL entered during installation and by including the XBAP file name, e.g. d.xbap. The latest version of the application is downloaded from the web server and run within the browser. The application is only downloaded once, until a new version is installed on the web server. The Discover client also includes the Discover Administration Utility. This is an additional WPF browser application that can be accessed via a separate XBAP package on the web server. To run the Discover Administration Utility, you must navigate to the root URL entered during installation and include the XBAP file name, e.g. erhosted.xbap. Discover Web Services The Discover browser client retrieves information from the server using a number of web services. The client identifies the URL of the services using the ExternalSettings.xml file in the root of the web site, i.e. the installation directory. The web services connect to a SIMS database to authenticate the user information, impersonating the user in the case of Windows credentials. They also connect to a Discover database to access data for graphing, the Windows account assigned to the web services must be granted sufficient rights to enable this. The web services also connect to the Shared Session Store database and the Windows account is granted rights during installation. When hosting multiple databases, the end users must be routed to a specific SIMS/Discover database pair. This is accomplished by using a routing provider. Two configurable routing providers are supplied with Discover or you can create your own custom router by writing one in.net. Before installing the Discover Web Services, you must ensure that the WCF Services have been enabled on the web server. You can add any necessary features via the Windows Server Manager. Discover Technical Guide 21

26 IMPORTANT NOTE: When upgrading the web services installation, you must be aware that if you chose to use a specific Domain account instead of the default ApplicationPoolIdentity account, the upgrade overwrites this and you must apply the change again by modifying the Discover application pool. As users do not need to be synchronised between the SIMS and Discover databases when using the Discover Web Services, the Discover User Synchronisation Scheduled Task can be disabled. The Discover Web Services can be installed using the Discover installation wizard. To install the Discover Web Services you must provide: the web site to install to a name for the web service 22 Discover Technical Guide

27 the root URL that clients will use to address the web site. If you are using multiple web servers behind a network load balancer, the Hosting URL Root location must be populated with the protocol and name/ip address of the network load balancer. the name of the Shared Session Store database and its SQL Server instance name Discover Technical Guide 23

28 Select the appropriate radio button to determine the Authentication method to use. This defines how the wizard will connect to the SQL Server to undertake the installation/upgrade process. It does not determine the authentication method used by the service. the name of a Discover database and its SQL Server instance name 24 Discover Technical Guide

29 the name of the paired SIMS database and its SQL Server instance name an installation directory for the Web Services. Discover Technical Guide 25

30 User Principal Name Format Login Where SIMS uses Windows users and Discover is accessed as a web browser application, you are required to enter your Windows credentials to log in. Discover supports the down-level logon name format (i.e. Domain\UserName). Support is provided for logging in using the User Principal Name (UPN) format, i.e. UserName@Example.Company.com. Although it is not possible to create a SIMS (not Windows) user with a name that matches the down-level logon name format, it is possible to create one in the UPN format. In the unlikely event that you are not using Windows users but do have SIMS users with a UPN style naming convention, you can turn off the UPN format support by entering the following key in the ExternalSettings.xml file: <noupnlogon>true</noupnlogon>. This file is located in a sub folder of the Discover Web Services folder called DiscoverWebService. Granting Database Access to the Application Pool Account The installation of the Discover Web Services grants the service accounts access to the specified SIMS and Discover databases. If you host multiple databases, access must be granted to the additional SIMS and Discover databases. Granting database access must be done from the command line. Please refer to the Granting Access Rights to the Web Services section in the Command Line Installation of Discover Components guide. Enabling Request Routing for the Web Services When hosting multiple databases, the Discover Web Services must route all requests from the browser clients to the correct SIMS/Discover database pair. The routing of users to a specific database pair is performed by a routing provider. The Discover Web Services must be configured to use a specific routing provider. 26 Discover Technical Guide

31 Editing the Web.Config File to Enable Routing Generally, database connection information is held in the web.config file. However, if Discover is accessed using a routing provider, the username is passed to the router and connection information is returned from the router. This enables a variety of rules to be established to determine which database should be used. These rules include: the direct lookup of the username in a text file or a database. the retrieval of connection information based on a user s location in Active Directory. the retrieval of connection information based on a pattern in the username. The web.config file is located in a sub folder of the Discover Web Services folder called DiscoverWebService. NOTE: If you have a web farm, every web.config file must be edited to reflect this change or you may experience intermittent connections when using Discover. The files can be edited and saved in Notepad. To enable routing, the web.config file must be edited and the highlighted lines shown in the following graphic must be uncommented. Discover Technical Guide 27

32 Additionally, locate the line that begins <add key="regexroutingfile" and update the value attribute to point to the location of the RegexRouting.xml file in the Discover Web Services folder. The application pool identity account must have rights to access the Discover.Routing.Routers.dll and any other necessary resources. Once routing has occurred, the results are stored in the shared session store for the duration of the session. The Regular Expression Router A regular expression router is supplied with Discover and this can be used to return connection information based on usernames that match regular expression rules. The regular expression router can be configured via an.xml file placed alongside the Discover.Routing.Routers.dll assembly in the Discover Web Services folder called RegexRouting.xml. A representation of the format of the file is displayed in the following graphic. You must add a <rule pattern> block for each pair of a school s SIMS and Discover databases, e.g. SIMS_SchoolA and Discover_SchoolA, etc. The rule pattern should be edited to match some information in the user name to identify which database pair the user should be connected to. For example, if the user name contains the school name, SchoolA will use the databases named SIMS_SchoolA and Discover_SchoolA. The regular expressions must match the given username pattern to the appropriate database pair. The regular expression rules are evaluated by the router in the order that they are defined. When a rule matches a defined pattern, the connection information within the rule definition is used to connect to the SIMS and Discover databases. 28 Discover Technical Guide

33 The regular expression rule elements have the following meanings: Element discoverinstance discoverdatabase authenticationinstance authenticationdatabase interactivelogonauthenticationprefix Description The SQL Server instance used to host the user s Discover database. The name of the user s Discover SQL Server database. The SQL Server instance used to host the user s SIMS database. The name of the user s SIMS SQL Server database. The prefix of the user s username in the SIMS SQL Server. This is typically the name of the user s SIMS database followed by an underscore (_). For example if a user s database is called SIMS and their username is user1 then the prefix is typically SIMS _ resulting in a SQL Server username of SIMS _User1. Using the Active Directory or LDAP Router An additional router has been provided with Discover to enable routing based on a user's information that is stored in the Active Directory. The LDAP Router is located in the Discover.Routing.Routers.dll assembly which can be found in the Discover Web Services folder. The parameters can be specified in the same way as the Regular Expression Router although the web.config file should be edited to reflect the following values: The LDAP Router looks up the user in Active Directory and provides their distinguished name for the purposes of regular expression matching. For example, the user MyDomain\jsmith may have a distinguished name of: A pattern can be supplied in the RegexRouting.xml to map OU=School A to the relevant SIMS and Discover databases. IMPORTANT NOTE: The application pool account must have sufficient permission to be able to read the Active Directory. Discover Technical Guide 29

34 Writing Your Own Custom Router Depending on your system setup, it may not be possible to derive connection information from a pattern in a username. If this is the case, you can build your own custom router using Visual Studio 2010 or later. You need to create a new,.net 4 class library project, add a reference to the assembly Discover.Routing.Interface.dll and implement the IRoutingProvider interface. A representation of the format of the file is displayed in the following graphic. Each method is supplied with a username during the login process and should return the appropriate information in the output parameters or return value. NOTE: The variable names correspond to the element tags previously mentioned. Implementations must be stateless and designed to return information as quickly as possible. Once your.net 4 class library is compiled and tested, it should be placed alongside the Discover.Shared.dll assembly on the web server. The web.config file should also be updated so that it points to the fully qualified type and assembly name of your assembly. IMPORTANT NOTE: As this does not constitute a SIMS product, support for writing your own custom router is not provided by the SIMS Service Desk. If you are not sure how to undertake this, please contact Capita Professional Services and log a request for a chargeable development service. Transferring Data from SIMS to the Discover Database(s) Data must be transferred from the SIMS database into the corresponding Discover database so that current data is available for the creation of graphs in Discover. Transfers are always performed by the SIMS Discover Data Transfer Service but can be initiated in various ways. The Discover Data Transfer Scheduled Task initiates a transfer according to the specified schedule details, you can also start the transfer process manually via the Discover Administration Utility. 30 Discover Technical Guide

35 IMPORTANT NOTE: When running the Transfer process for the first time after installation, you must only transfer the current years' data. Once the initial Transfer process has completed successfully, you can select to transfer multiple years' data. The Discover Administration Utility is installed with both the Discover desktop and browser clients. Everyone can access the Discover Administration Utility for the database that they are configured to connect to. The Discover Administration Utility can be configured to enable specific users to access multiple SIMS and Discover database pairs. In order to achieve this, the Discover Administration Utility must be able to read a Hosted Settings file listing the details of the SIMS/Discover database pairs. Users only need to be granted full permissions in a single SIMS database to enable them to initiate the Transfer process for all SIMS/Discover database pairs. Other activities require specific permissions to be granted within individual databases. An automatic safeguard has been incorporated to prevent you from inadvertently initiating the Transfer routine when one is already underway. In the event of a hardware failure or disc corruption, any active Transfer routines are reset when the Transfer Service is next started. Please refer to the Permissions information in the Discover User Guide for further details regarding access to the various functions in the Discover Administration Utility. Permissions Required to Access the Discover Administration Utility for Hosted Installations If you are a multiple database user, your permissions within the Discover Administration Utility are initially determined by the permissions assigned to you in the primary SIMS database. Therefore, it is advisable to enter the details of a primary database that gives you the widest set of permissions available. When you try to perform a function against a different database, the application checks your permissions to access that specific database and you cannot continue further without assigning suitable permissions. For example, if you have been assigned the Edit Assessment Settings permission in the primary database, e.g. School_A, you can access the Assessment processes. However, if you attempt to carry out the same function in the database for School_B without having been assigned the Edit Assessment Settings permission in that specific database, the application prevents you from continuing. The ability to initiate the data Transfer process is treated differently from carrying out general functions. All multiple database users must have been assigned the Transfer Run permission in the primary database to enable them to access the process. However, you do not need to have been assigned permission in all the other databases to initiate a transfer request for one of those databases. If you are using the desktop application, you must have access to all Discover databases to run a transfer but you do not need to have been assigned the Transfer Run permission in each database. Discover Technical Guide 31

36 Considerations when using the Browser Client The Discover Administration Utility browser client (XBAP) is installed by the Discover Web Service installation. It is accessed by navigating to the Hosting URL Root and web site, specified during installation, with the XBAP file name, e.g. istrations.browserhosted.xbap. The Discover Web Service must be configured to read a hosted.xml file in order that multiple transfers can be initiated for multiple databases. This can be achieved by placing the file in the installation directory or by adding a hostedsettingsfile key to the web.config file. Users who should have access to multiple databases must be defined as a 'host' user by the Routing Provider. If you are using the Regular Expression router or the LDAP router provided with Discover, an <ishost> element with a value of true can be added to the rule for specific users. The SIMS database specified in the rule is considered to be the master database for permissions. Example: <rule pattern="^administrator^"> <discoverinstance>discoverserver</discoverinstance> <discoverdatabase>discover_schoola</discoverdatabase> <authenticationinstance>simsserver</authenticationinstance > <authenticationdatabase>schoola</authenticationdatabase> <interactivelogonauthenticationprefix>schoola_</interactiv elogonauthenticationprefix> <ishost>true</ishost> </rule> If you are using a custom router, your implementation of the RouteToDiscoverFromUserName method must return true for users who should have access to multiple databases. Considerations when using the Desktop Client The Discover Administration Utility desktop client is installed with the Discover desktop client. The Discover Administration Utility is also installed with the Discover Services and can be started by running the Discover.Administrations.Desktop.exe from the Services installation directory. It is designed to connect to the same SIMS and Discover database pair as the installed client. Consequently, it utilises the database connection details from the configuration file on the client machine. 32 Discover Technical Guide

37 To access multiple databases for data transfer, the client must be configured to read a hosted.xml file, either by placing the file in the installation directory or by adding a hostedsettingsfile key to the Discover.Designer.Desktop.exe.config file. The authentication database in the configuration file, which is entered during installation, is deemed the master SIMS database for permissions. When initiating a transfer for multiple database pairs using the desktop client, the logged-in user must have permissions to write to every Discover database selected. The application places a flag in each Discover database to request that the Data Transfer Service perform a transfer. Configuring Scheduled Discover Transfers If you have installed Discover using the installation wizards, the Discover Data Transfer Task is created automatically as an integral part of the installation process. This task enables the transfer of data between the SIMS and Discover databases. However, if you have installed Discover from the command line, it is possible to make manual changes to this task by modifying the contents of the Discover.Warehouse.TriggerConsole.exe.config file. This file can be found in the C:\Program Files\SIMS\Discover Services folder. It is possible to specify the DiscoverServerName and DiscoverDatabaseName settings by editing the file using a text editing programme. A parameter can be supplied to the Discover.Warehouse.TriggerConsole.exe, which is accessed when the Scheduled Task is run. Using this parameter, you can create a Scheduled Task to automatically update a previous year's data at a different frequency from the current academic year, e.g. monthly instead of daily. This can be achieved by copying the existing Scheduled Task and adding the new parameter, e.g. /Order="-1" (for Last Year), /Order="-2" (for Two Years Ago). Discover Technical Guide 33

38 Installing the Discover Desktop Clients Discover desktop clients can be installed in the following ways: manually, using the supplied Windows Installer. Please refer to the Discover Typical Installation Guide for further information. from the command line. Please refer to the Installing the Discover Client section of the Command Line Installation of Discover Components guide for details. from SOLUS 3. The Discover Client installer can be configured to use a redirection file, whether on a local path, a Uniform Naming Convention (UNC) path or a mapped drive. This enables the Discover client database settings to be maintained centrally. Please refer to the Redirecting the Discover Client Installation Wizard section of the Command Line Installation of Discover Components guide for further information. Enabling the Browsers for the XBAP Application When deploying the browser client, browsers may need to be prepared to accept the XBAP application by enabling the XAML browser applications and installing a certificate. Your users can then start the application by navigating to the Hosting URL Root and web site, specified during installation, with the XBAP file name, e.g. ner.browserhosted.xbap. The latest version of the application is downloaded, if required, before the application runs. Internet Explorer 9 and later versions have XBAP applications disabled by default. XAML browser applications must be set to Enable for the relevant zone. This setting is located under Tools Internet Options Security (tab) Custom level (button) in Internet Explorer. Please ensure that.net Framework version 4.0 is installed on the client machine. IMPORTANT NOTE: Please bear in mind that the web browser session can only be left inactive for a period of 15 minutes before you are required to refresh the browser and repeat the login procedure. Installing the Public Certificate on a Client Machine If your client machines are connecting to the web server over the Internet and not via a trusted Intranet, it is necessary to run a security certificate on each workstation that will be accessing Discover as a hosted application. The security certificate is called CCSDiscoverPublic.cer and is located in a sub folder of the Discover Web Services folder called Hosted Support Files. 34 Discover Technical Guide

39 1. Open Internet Explorer and select Tools Internet Options to display the Internet Options dialog. 2. Select the Content tab and click the Certificates button to display the Certificates dialog. Discover Technical Guide 35

40 3. Click the Import button to display the initial page of the Certificate Import Wizard. 4. Click the Next button to display the File to Import page. 5. Click the Browse button and navigate to the stored location of the security certificate. 36 Discover Technical Guide

41 6. Click the Next button to display the Certificate Store page. 7. Select the appropriate storage location for the certificate and click the Next button to display the Completing the Certificate Import Wizard page. IMPORTANT NOTE: To prevent the Security Warning message from being displayed when running the Discover XBAP as an Intranet application, it is necessary to install the CCSDiscoverPublic.cer file to the Trusted Publishers store on the client machine. It may also be necessary to install it to the Trusted Root Certification Authorities store. However, this should only be done if installation to the Trusted Publishers store is not sufficient to prevent the Security Warning message from being displayed. Discover Technical Guide 37

42 8. Click the Finish button to complete the import process. 9. Click the OK button to close the Certificate Import Wizard. 38 Discover Technical Guide

43 03 Additional Setups and Troubleshooting 03 Additional Setups and Troubleshooting Amending the Hosted Settings File to Reflect the SIMS and Discover Database Names Modifying the Service Application Settings Using the Discover Log Viewer Utility Recovering from a Partial Server Failure on a Hosted Installation. 45 Enabling Roles and Features in Windows 2016 Server Manager Amending the Hosted Settings File to Reflect the SIMS and Discover Database Names A sample Hosted Settings file (hosted.xml)has been provided and can be located in a sub folder of the Discover Web Services folder called Hosted Support Files. Please amend and update the contents of this file to reflect the names of all your school s SIMS and Discover database pairs, e.g. SIMS_SchoolA and Discover_SchoolA, SIMS_SchoolB and Discover_SchoolB, etc. Discover Technical Guide 39

44 03 Additional Setups and Troubleshooting If you want to scale out the application server or have entirely separate schedules for different groups of databases, you must run the Install Discover Services option of the Discover Server Setup on multiple machines, either virtual or physical and amend the Hosted Settings file (hosted.xml) so that the data transfer and group synchronisation is performed only on the required subset of database(s). IMPORTANT NOTE: Only SIMS/Discover database pairs that are currently active and in use should be listed in the Hosted Settings file (hosted.xml). This reduces errors and unnecessary delays. The XML elements have the following meanings: Element <?xml version="1.0" encoding="utf-8"?> hostedsettings site description (attribute) simsserver simsdatabase interactivelogonauthenticationprefix discoverinstance discoverdatabase Description XML declaration Root element One site element must be supplied for each SIMS/Discover database pair. A 'friendly' name for the database pair. The SQL server instance used to host the SIMS database. The name of the SIMS SQL server database. The prefix of the user's username in the SIMS SQL server. This is typically followed by an underscore. For example, if the database is called SIMS and a user's username is user1, this results in a SQL server username of SIMS_User1. The SQL server instance used to host the Discover database. The name of the Discover SQL server database. Discover components can be configured to read a specific hosted settings file at a fixed location. This is achieved by adding a hostedsettingsfile key to the component s configuration file, for example: <appsettings>... <add key="hostedsettingsfile" value="[full path to hosted.xml]" />... </appsettings> 40 Discover Technical Guide

45 03 Additional Setups and Troubleshooting The value can be any valid file path. The Windows Account running the component must have read access to the file. The following components and their related file names can consume a hosted settings file with their configuration file: SIMS Discover Data Transfer Service* Discover.Warehouse.Service.exe.config SIMS Discover Group Synchronisation Service* Discover.DataEngine.DataViewMonitor.Service.exe.config Discover Data Transfer scheduled task trigger console Discover.Warehouse.TriggerConsole.exe.config Discover Administration Utility desktop client* Discover.Administrations.Desktop.exe.config Discover Web Services web.config * This component must be restarted in order for changes to the hosted settings file to take effect. Modifying the Service Application Settings There are a number of application settings that can be applied to change the configuration of the service, if this is deemed necessary by the System Manager. These settings can be changed in the <appsettings> element of the Discover.Warehouse.Service.exe.config file located in the Discover Services directory. If you want to edit the service application settings, double-click the file name to open it in Notepad or an xml editing programme. Discover Technical Guide 41

46 03 Additional Setups and Troubleshooting The following settings can be inserted manually into the Discover.Warehouse.Service.exe.config file. Key Default Value in Units MaxAttemptCount 5 SleepTime (ms) 60,000 i.e. (60s) SIMSConnectTimeout (s) 15 SIMSCommandTimeout (s) 300 i.e. (5 mins) DiscoverConnectTimeout (s) 15 DiscoverCommandTimeout (s) DiscoverBulkCopyTimeout (s) 300 i.e. (5 mins) 300 i.e. (5 mins) DiscoverBatchSize 1000 It is also possible to control the number of simultaneous group synchs by modifying the Discover.DataEngine.DataViewMonitor.Service.exe.config file. You need to enter the HostedMaximumNumberOfSimultaneousTransfers key and set the value to the maximum number of simultaneous transfers allowed. If you make any changes, please ensure that you select Save when closing the instance of Notepad or the xml editing programme. Using the Discover Log Viewer Utility If an issue or error occurs whilst using Discover, it is suggested that you consult the Discover.LogFile.log. This is a text file and can be found in the C:\Windows\ServiceProfiles\NetworkService\AppData\Local\Di scover folder on the machine that the service is running on. A log viewing utility can also be found in the same installation folder and this enables you to view the file in a tabular format for ease of understanding. 42 Discover Technical Guide

47 03 Additional Setups and Troubleshooting 1. Double-click the Discover.LogViewer.exe to open the utility. 2. Click the File button, then click the Load button to display the Open dialog. 3. Navigate to the location of the log file. This is located in the local application data directory of the current user. For example, in Windows 7, when logged on as MyUser, the log file is located in the C:\Windows\ServiceProfiles\NetworkService\AppData\Local\ Discover folder. 4. Highlight the file name and click the Open button to load the file. Discover Technical Guide 43

48 03 Additional Setups and Troubleshooting The messages and details in the text file are displayed in a tabular format for ease of viewing. 5. Highlight a specific line of text and click the Row Detail chevron button on the far right-hand side to view additional information relating to the message. 6. Click the Row Detail chevron button again to close the Row Detail column when you have obtained the information required. 7. Click the Close button to exit the Discover Log Viewer utility. 44 Discover Technical Guide