Our goal is to provide a simple and consistent way of contributing to and collecting stakeholder comments from NICE consultations
Table of contents
This service provides a way for NICE stakeholders to comment directly on NICE consultations and documents to provide their viewpoint; and a way for NICE teams to request comments and process them for response which doesn’t require repetitive manual handling.
Consultation is a key part of developing NICE guidance, including NICE quality standards. The consultation processes enable external organisations and individuals to comment on guidance content at specific stages in the development process, and feed into the decision-making process.
What is our motivation for building this product or service?
- NICE efficiencies
- Increase stakeholder engagement
- Improve quality of responses given by NICE
- Internal teams at NICE who consult on the guidance they are producing by collecting comments from external stakeholders
- Our external stakeholders are the people who the guidance and standards that NICE produces affect and who want to provide their views on the development of these, so that their needs and priorities are reflected in the final guidance
What problem will it solve for people?
- Less manual handling when collating comments
- Less variation for stakeholders between different types of consultation - Secondary
- Able to comment against specific parts of a document or more generically
- Easier for NICE to tell which part of the document is being commented on
What problem will it solve for our organisation?
- Efficiency savings for NICE by reducing manual handling during collation
What do we need to measure against these outcomes?
- Time taken to collate results
- End to end time taken for consultation process
- Number of comments received
- Number of distinct organisations commenting
- Improved quality of responses / lower error rate
Consultations sits below Varnish so is under the main niceorg domain. It pulls data from InDev via an API and stores data in SQL Server.
+---------+
+---------- Varnish -------------+
| +----|----+ |
| | |
| | |
+-------v------+ +----v----+ +-------v-------+ +---------------+
| Guidance Web | | Orchard | | Consultations -----> SQL Server DB |
+--------------+ +---------+ +-------^-------+ +---------------+
|
|
|
+---|---+
| InDev |
+-------+
- Varnish for infrastructure-level routing
- .NET Core 2 on the server
- SQL Server as our database
- Entity Framework Core as an ORM
- EF Core In-Memory Database Provider for integration tests
- React for the UI library
- [Volta] (https://volta.sh/) Javascript manager for having multiple version of node js on the same machine
- Create React App for configless React
- Jest for JavaScript tests
- ASP.NET Core JavaScript Services for rendering JavaScript server side in .NET
- ESLint for JavaScript linting
- SASS as a CSS pre-processor
- Modernizr for feature detection
- WebdriverIO for automated functional testing
- [IDAM] (https://github.com/nice-digital/identity-management) Authorisation and Authentication
- [Redis] (https://redis.io/) an in-memory caching application used by IDAM to cache Auth0 tokens
- NICE Design System for NICE styling
- NICE Icons for icon webfont
- Install KDiff to be able see diffs from integration tests
- Install SQL Server and SQL Server Management Studio (SSMS)
- Create a blank database called "Consultations" using SSMS. Set account running visual studio as db_owner (Your domain username or SUDO account if running as administrator)
- Optionally restore Consultations database from a backup. (if left blank, EF Migrations will run and create everything)
- Clone the project
git clone https://github.com/nice-digital/consultations.git - Open Consultations.sln
- Create user secrets
- Right click on project
- Select 'manage user secrets'
- Copy and paste the default user secrets from the Secrets section
- Replace the {DatabaseServer} and {DatabaseName} in the connection string with the details from the database created in step 3. SQLServer Express often creates an instance, so your local server name might be in the form of {LaptopName}//SQLEXPRESS
- Ask devops for read access to our current deployment pipeline and copy all the test environment values for the following secrets file sections
- Logging
- Feeds
- WebAppConfiguration
- Encryption
- ConsultationList
- Set WebAppConfiguration PostLogoutRedirectUri to "http://niceorg:81"
- Set WebAppConfiguration RedirectUri to "http://niceorg:81/signin-auth0"
- Install Redis on your machine. See Redis server for more details
- Run the application (Hit F5 or the green triangle on the toolbar next to ‘IISExpress’)
- You may need to add a line to your hosts file (C:\Windows\System32\drivers\etc\hosts) pointing "niceorg" at 127.0.0.1
- You may need to create a Self Signed Certificate for "niceorg" on your machine and bind it to port 44306 to stop browser warnings. More detailed instructions are under Creating Self Signed Certificate for niceorg
- Dependencies will download (npm and NuGet) so be patient on first run
- The app will run in IIS Express on http://localhost:44306/
- Install Volta to ensure the version of node on you machine does not clash with the node version needed for Consultations. Volta will detect the node version automatically from package.json
- Open up a powershell terminal
- cd into consultations\Comments\ClientApp
- run 'npm ci'
- run
npm startif Startup is usingUseProxyToSpaDevelopmentServer. This runs a react dev server on http://localhost:3000/. - There is another README file in consultations\Comments\ClientApp which goes into more detail if
npm startdoes not work immediately.
- Optionally, Run
npm testin a separate window to run client side tests in watch mode - If you don't have it already, you will need to go into Identity Management for the environment you are working with e.g. https://test-identityadmin.nice.org.uk/ and give youself Administrator access to Consultations
If you have followed the instructions from the Setup section above then consultations should be integrated with test.
The data in Indev test can be patchy. Creating a new consultation is recommended. Instructions to create consultations are listed in Creating a consultation in Indev.
Indev can be integrated into consultations locally so the whole API chain can be debugged. See the Indev repository for more instructions.
- Create a new project
- Go to Timeline and click Consultation
- Set the start date and end date, ensure that today's date is between the two dates
- Set the consultation number as 1
- Hit save
- Go to Upload and drag in any templated guidance document.
- Set the type as "Draft Consultation Document (online commenting)"
- Hit Upload and wait for the message to say "Converted!" then hit Close
- Schedule the guidance for Now and hit Save
- go to https://test-indev.nice.org.uk/golive and hit Go Live
If you go to the list page in consultations and search for this consultation it should be there. Clicking on the consultation should take you to the guidance page with all the links to add comments etc...
Below is a powershell script which will create and bind an SSL certificate for niceorg. This needs to be run as administrator.
Once the script has run, you will need to import the certificate into your Trusted Root Certificates.
- Log into your sudo admin account
- type "manage computer certificates" into the search bar, go into "Manage computer certificates", it will ask for admin password again.
- Open up Personal > Certificates
- Find the certificate for "niceorg" and export it to a folder locally
- Open up "Trusted Root Certification Authorities > Certificates"
- Delete and existing certificates for "niceorg"
- Right click "Certificates" and go to "All Tasks > Import"
- Follow the instructions to import the certificate Exported in step 4
If you return to your normal user account and re-start your project, you should not get any more security errors in your browser
$cert = New-SelfSignedCertificate `
-DnsName "niceorg" `
-CertStoreLocation "cert:\LocalMachine\My" `
-KeyExportPolicy Exportable `
-FriendlyName "niceorg" `
-NotAfter (Get-Date).AddYears(5)
$store = New-Object System.Security.Cryptography.X509Certificates.X509Store("Root","LocalMachine")
$store.Open("ReadWrite")
$store.Add($cert)
$store.Close()
$guid = [guid]::NewGuid().ToString()
netsh http delete sslcert ipport=0.0.0.0:44306
netsh http add sslcert ipport=0.0.0.0:44306 `
certhash=$($cert.Thumbprint) `
appid="{$guid}"
- First try to copy the secrets file from another developer who has had comment collection working before.
- If you cannot find another developer with a secrets file, you can copy the format below.
{
"ConnectionStrings": {
"DefaultConnection": "Data Source={DatabaseServer};Initial Catalog={DatabaseName};Persist Security Info=True;Trusted_Connection=True;"
},
"Logging": {
"IncludeScopes": false,
"LogFilePath": "Serilog-{Date}.json",
"LogLevel": {
"Default": "Debug",
"System": "Information",
"Microsoft": "Information"
},
"UseRabbit": false,
"UseFile": true
},
"AppSettings": {
"Environment": {
"Name": "local",
"SecureSite": "false"
}
},
"Feeds": {
"ApiKey": "<indev API key>",
"IndevBasePath": "<indev base path>",
"IndevPublishedChapterFeedPath": "<feed path>",
"IndevDraftPreviewChapterFeedPath": "<feed path>",
"IndevPublishedDetailFeedPath": "<feed path>",
"IndevDraftPreviewDetailFeedPath": "<feed path>",
"IndevPublishedPreviewDetailFeedPath": "<feed path>",
"IndevListFeedPath": "<feed path>",
"CacheDurationSeconds": 60,
"IndevIDAMConfig": {
"Domain": "<InDev IDAM Domain>",
"ClientId": "<Auth0 Client Id>",
"ClientSecret": "<Auth0 Client Secret>",
"APIIdentifier": "<Auth0 API Identifier>"
}
},
"WebAppConfiguration": {
"ApiIdentifier": "<Auth0 API Identifier for comment collection>",
"ClientId": "<Auth0 Client Id for comment collection>",
"ClientSecret": "<Auth0 Client secret for comment collection>",
"AuthorisationServiceUri": "<Auth0 Authorisation service URI for comment collection>",
"Domain": "<Auth0 Domain comment collection>",
"PostLogoutRedirectUri": "<Auth0 Post Logout Redirect Uri>",
"RedirectUri": "<Auth0 Redirect Uri>",
"GoogleTrackingId": "<google tracking id>",
"RedisServiceConfiguration": {
"ConnectionString": "<redis server URL (127.0.0.1:port if running locally)>",
"Enabled": true
}
},
"Encryption": {
"Key": "<Encryption key for encrypting comment text>",
"IV": "<Initialisation Vector for encrypting comment text>"
},
"ConsultationList": {
"DownloadRoles": {
"AdminRoles": [ "<List of Admin roles>", "<List of Admin roles>" ],
"TeamRoles": [ "<List of team roles>", "<List of team roles>", "<List of team roles>" ]
}
}
}
This application uses a data store called Redis to capture and store Tokens from Auth0. You will need to run a local version of Redis
There are a number of ways to run Redis on windows: - Windows subsystem for Linux (WSL)
- Chocolatey
- A docker/podman container
Getting Started with Redis - https://redis.io/docs/getting-started/
Installing Redis on Windows (Using WSL) (https://redis.io/blog/install-redis-windows-11/)
spa.UseReactDevelopmentServercan be slow so try usingspa.UseProxyToSpaDevelopmentServer("http://localhost:3000");instead within Startup.cs.- Need to ensure that nothing else is running on port 80, otherwise you will encounter a socket exception error when running in debug.
- Exception: OpenIdConnectAuthenticationHandler: message.State is null or empty. -- caused if login is attempted without redis, clear your cookies and login again.
- It might take a few F5's, visual studio restarts and cookie clears to get all the various services/applications to start co-operating
- Make sure you sign into the main consultation window which pops up when you run the project
- Error message saying "Something must have gone slightly wrong!" - Have a look at the logs in Auth0 tenent. This error is coming from the IDAM signin. Check in secrets.json that the WebAppConfiguration > ClientId and WebAppConfiguration > ClientSecret section are correct for the API Identifier.
The project uses serveral layers of tests:
- C# low-level unit tests, run via xUnit, asserted with Shouldly. See Comments.Test/UnitTests.
- C# 'integration' tests (approval based of server rendered HTML), run via xUnit, asserted with Shouldly, diffed with Kdiff. See Comments.Test/IntegrationTests.
- JavaScript unit tests via jest. See Comments/ClientApp/src.
- Functional high-level tests, via webdriver.io.
We use Code first Entity Framework migrations to update the consultations database
To update the database
- add a new property to the relevent class in Consultations > Comments > Models > EF
- in visual studio go to Tools > NuGet Package Manager > Package Manager Console
- in the package manager console window run the command Add-Migration [give your migration a useful name] eg Add-Migration AddCommentCreationDate
This will create a new migrations script in Consultations > Comments > Migrations - when the comment collection is next hit the changes in the migration script will be applied to SQL.
A new column will be created in __EFMigrationHistory to flag that the migration has been run.
See the Consultations Sharepoint site
| Environment | URL |
|---|---|
| local | https://local.nice.org.uk/consultations/ |
| Test | https://test.nice.org.uk/consultations/ |
| Alpha | https://alpha.nice.org.uk/consultations/ |
| Live | https://www.nice.org.uk/consultations/ |
For further information about the recommended ReadMe structure plus a 'how to' for regenerating the table of contents, follow the instructions in DIT Engineering - ReadMes