Repository containing the Open Sourced code for the Hub and Hub Legacy projects - including Corporate Calendar, Media Request Manager and others.
This readme has information for Infrastructure / DevOps teams, Application Developers, and Configuration of the applications. All team members should read this to gain familiarity with the various pieces and how they all fit together.
The following is an example setup of the IIS web site, SQL Server database, and Active Directory groups. This is not the only way to implement, as each team will have its own policies to follow; however, consider the following as a reference of issues to be addressed.
Active Directory Groups play a large part in securing access to the site and filesystems. Groups are used to provide NTFS access and certain permissions within the application code. Keep in mind, that not ALL the privileges within the application code are provided through Active Directory. Within the Corporate Calendar (Legacy) application, there is a user management panel (/Legacy/Calendar/Admin/UserList.aspx), and within that are roles: Read Only, Editor, Advanced, Administrator, System Administrator. See (link) for more; in this section we will only discuss securing the site, the database and granting initial access to the application through Active Directory.
For the following will use DIR as the Active Directory domain.
An Active Directory (AD) "service" account is used as the identity of the Application Pools in order access the database. The following are some best practices:
These groups are used to authenticate to websites, and require NTFS READ permission on application folders. Names are just examples, and corporate policy / team standards should be followed
In addition to these groups, others are identified in the Legacy configuration file to authorise certain users for certain roles in the Legacy application. These groups can be nested in the TSTRS/USERS group
It is best to first create the folder, which will be required when the Website is created, and finally set permissions which need to IIS App Pools to exist.
\\env.iis\applications\Gcpe.Hub
IIS Application Root
\\env.iis\applications\Gcpe.Hub\Configuration
Location of configuration files for the Hub application and Legacy Applications.
Code expects this relative path and name.
\\env.iis\applications\Gcpe.Hub\Log Files
IIS Logging and Hub application logging (if enabled).
This location and name can be changed.
See Hub.WebApp.appSettings.json Logging section to enable and configure logging.
\\env.iis\applications\Gcpe.Hub\Web Site
Main Web Site – the Hub..NET Core 2.2 application.
Name of the directory can be changed.
\\env.iis\applications\Gcpe.Hub\Web Site - Legacy
Hub Legacy applications.ASP .NET 4 application
Name of directory can be changed.Two application pools are required.
One website is created, named Gcpe.Hub, using the "Web Site" folder and Gcpe.Hub App Pool, and Logging configured as desired. W3C logs can be placed in the Log Files folder used by the application, or in a location as per applicable standards.
In this website, create an Application named "Legacy" using the "Web Site - Legacy" folder and Gcpe.Hub_Legacy App Pool.
A valid SSL certificate is highly recommended for the website, especially if it will be accessible form the internet.
Additional Components for Reporting:
The folders used by the application require the following permissions in addition to what ever is required by the system. AppPools can be identified with the local reference "IIS AppPool_\<appPoolName\>"_
In order to keep the above table as brief as possible, here is a further explanation of how each folder is used.
Under this directory there will be two files:
Hub.Legacy.appSettings.config
This is the configuration for the legacy applications.
It is pulled into the web.config via the appSettings section file attribute.
Please note that the connection strings for the Legacy applications are in the Web.Config file.
Hub.WebApp.appSettings.json
This is the configuration for the hub (.NET Core) application. This file will contain the connection string for the Hub.
Contains application code for the Hub, the main web site. This is a .NET Core 2.2 application.
Contains the application code to all the Legacy components: Corporate Calendar, Media Relations / Contacts, News Release Management and News Release File Management. All the Legacy components exist under a single ASP .NET 4.0 web application.
The application(s) can optionally write log files, and require a location to do so. This can optionally be used for the IIS W3C log files as well
A database administrator should create the database in advance according to their corporate/team standards and provide required access for analysts, developers and the service account.
All connections to SQL Server will be with Integrated Security = true in the connection strings, so the service account used for their identity will require access to the database (Gcpe.Hub).
This example will create a SQL Login for the Test Service account DIR\HUBSVCT , create a user in the Gcpe.Hub database, create a role to allow execution of Table and Scalar functions, and grant required roles to the service account.
USE [master]
GO
CREATE LOGIN [DIR\HUBSVCT] FROM WINDOWS WITH DEFAULT_DATABASE=[Gcpe.Hub]
GO
USE [Gcpe.Hub]
GO
CREATE ROLE db_executor
GO
GRANT EXECUTE TO db_executor
GO
CREATE USER [DIR\HUBSVCT] FOR LOGIN [DIR\HUBSVCT]
GO
USE [Gcpe.Hub]
GO
ALTER ROLE [db_datareader] ADD MEMBER [DIR\HUBSVCT]
ALTER ROLE [db_datawriter] ADD MEMBER [DIR\HUBSVCT]
ALTER ROLE [db_executor] ADD MEMBER [DIR\HUBSVCT]
GO
Developers will require db_owner access to pre-production databases to create/manage the database schemas. It's best practice that the same accounts not have db_owner in production to prevent mistakes targeting the wrong database. Often developers only want db_datareader access to production database, but they may use a different account in their operator role.
Similar T-SQL used to create the Login/User for the service account can be used to provide the developer groups access, using the desired roles.
Within the Media Relations / Contacts application (/Legacy/Contacts), Active Directory groups are used for additional logic and security.
In the Hub.Legacy.appSettings.config, there are two group settings: ContributorGroups and AdminGroups. See Configuration / Groups Configuration and Permissions Matrix
The assumption here is that the DBAs have created a Gcpe.Hub database, assigned the service accounts and Active Directory access. The following is to load the objects (tables, views, etc), and load an initial dataset. The initial data set contains records that are required for certain (current) system logic to work correctly; ids and names that are expected to trigger additional logic.
Run the following command:
sqlcmd -S localhost -i _sqlcmd.master.sql -v path="path to /db-scripts"
Important Note for developers:
You will need to access your Windows Active Directory.
Please gather information for all your AD domains (dev, test, prod, etc). You will need the url and domain name.
And of more importance, for developers that do NOT log their machines into the domain, credentials will be required to query the AD. Environment variables will be required for these developers to mimic Authorization/Authentication.
GcpeHubDbPassword: Database User Password used for developer only connections. Same as password entered in HB_SDLC_DVLPR to match db-scripts/gcpe.hub-02-create-login_hb_sdlc_dvlpr.sql
Note: if GcpeHubDbUserID and GcpeHubDbPassword environment variables are set, connection strings will be changed from Integrated Security=true to Integrated Security=false. These values are added as User ID and Password.
.NET Framework 4.6.2 Developer Pack link
.NET Core 2.2 SDK and Runtime link
Gcpe.Hub.WebApp is a .NET Core application. .NET Core 2.2 is a separate download from the .NET Framework
TypeScript 2.3 SDK for Visual Studio 2017 link
Open XML SDK 2.5 & Open XML SDK Tool 2.5 link
Visual Studio 2017 Community Edition link
This code base can be developed and run using Visual Studio 2017 Community Edition, however; 2017 Professional Edition is preferred.
SQL Server Developer Edition link
SQL Server Management Studio link
Web Essentials 2017 VS extension link
This is required to generate/identify the minified version of our site.css file in the Gcpe.Hub.WebApp project and the Gov.News.WebApp projects. This projects will not build locally without site.min.cs, so it must be generated locally, by installing web essentials
TypeScript Definition Generator VS extension link
This used to be included in Web Essentials, but it is no longer. It is a tool for generating typescript .d.ts files from C# classes. See Gcpe.Hub.WebApp in the models folder there are C# objects with generated .d.ts files (click the arrow to see). Note: this only works on Windows 10
Node.js with NPM (version 8.11 or later, this written using 10.4.1) link
Assumes administrative privileges on the machine.
.NET Framework, TypeScript SDK, Open XML SDK - just double-click and use defaults.
Visual Studio installation, you will be presented with options for adding Workloads and Components.
At a minimum, you must install:
SQL Server Developer Edition install using the Basic option (defaults), then Customize.
Customizations
SQL Server Management Studio, double-click and use defaults
Web Essentials and TypeScript (if applicable) extensions, just double-click.
Node.js, follow installation instuctions. If using the Windows Installer, double-click and accept defaults. Ensure node is in the path.
Install bower and gulp globally, from a command prompt:
npm install -g bower
npm install -g gulp
Ensure MSBUILD is on your PATH, if it is not already there (Community Edition does not add VS tools to PATH).
set PATH=%PATH%;C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\MSBuild\15.0\bin;
By default, the local SQL Server accepts only Windows Authorization, we need to allow for SQL Server Authorization.
Create a local version of the Gcpe.Hub database. This will create the database, a database user, and seed the tables.
Run the following command:
sqlcmd -S localhost -i _sqlcmd.developer.sql -v path="path to /db-scripts"
Under the /Configuration directory, there are 2 template files: Hub.Legacy.Template.appSettings.config and Hub.WebApp.Template.appsettings.json. Copy these files and rename as: Hub.Legacy.Debug.appSettings.config and Hub.WebApp.Debug.appsettings.json. This should be done for each build/runtime configuration and should remain in /Configuration directory. DO NOT CHECK THESE INTO SOURCE CONTROL
Note that at build time, the configuration specific files will be copied to /Configuration as Hub.Legacy.appSettings.config and Hub.WebApp.appSettings.json. In this way, we mimic the production layout and file naming for configuration.
This is the collection of applications (Calendar, Contacts/Media Relations, News Release Management) that are bundled together. These will be deployed as a sub-site of the Hub.WebApp. Configuration for Hub.Legacy is considerable. All configuration keys must in Hub.Legacy.*.appSettings.config must be populated, but for immediate development purposes, set the following values to match your system:
These values will be used to build up various connection strings in the applications at runtime. For development scenarios, see environment variables.
This is the HUB proper. It is a .NET Core application. Configuration is significantly easier.
There are two solutions: hub.web.opensource.sln (Hub.WebApp) and hub.legacy.opensource.sln (Hub.Legacy).
There is a define preprocessor symbol (LOCAL_MEDIA_STORAGE). This controls whether the application uses local storage (filesystem and database) or Azure Cloud based storage. By default, this is NOT defined and will use Azure Cloud Storage. This only matters if the Legacy News / Release Management application is used. See News / Release Management Configuration
This can be added to the Project (Gcpe.Hub.Legacy.Website) Properties... Build -> Conditional compilation symbols.
Or this can be added as a parameter to msbuild (note that you must specify ALL DefineConstants in this parameter - it overrides the value in the csproj file).
msbuild Hub.Legacy\Gcpe.Hub.Legacy.Website\Gcpe.Hub.Legacy.Website.csproj /t:Clean,Build /p:SolutionDir=C:\gcpe-hub\ /p:Configuration=Debug /p:DefineConstants="DEBUG;TRACE;LOCAL_MEDIA_STORAGE"
Note: If you encounter an issue when running through the IDE like "Could not find a part of the path … bin\roslyn\csc.exe". Try the following in the Package Manager console:
PM> Install-Package Microsoft.CodeDom.Providers.DotNetCompilerPlatform
We will build and publish to a local filesystem first, then copy the output to the IIS server. The /p:DeleteExistingFiles=True switch will not only delete files, but will delete the base folder. We need to leave those intact on IIS directories due to specific permissions and site configuration.
Ensure msbuild, bower, gulp are on your path
Open command prompt at root of code (ex. C:\gcpe-hub)
Publish to a local filesystem mirroring IIS layout (ex. C:\pub)
Build and Publish the Release version of Hub.Web (see LOCAL_MEDIA_STORAGE Preprocessor Symbol)
msbuild Gcpe.Hub.WebApp\Gcpe.Hub.WebApp.csproj /t:Clean,Build,Publish /p:SolutionDir=C:\gcpe-hub\ /p:Configuration=Release /p:DeployOnBuild=true /p:DeployDefaultTarget=WebPublish /p:WebPublishMethod=FileSystem /p:PublishProvider=FileSystem /p:publishUrl="C:\Pub\Web Site" /p:DeleteExistingFiles=True
Build and Publish the Release version of Gcpe.Hub.Legacy.Website
msbuild Hub.Legacy\Gcpe.Hub.Legacy.Website\Gcpe.Hub.Legacy.Website.csproj /t:Clean,Build,Publish /p:SolutionDir=C:\gcpe-hub\ /p:Configuration=Release /p:DeployOnBuild=true /p:DeployDefaultTarget=WebPublish /p:WebPublishMethod=FileSystem /p:PublishProvider=FileSystem /p:publishUrl="C:\Pub\Web Site - Legacy" /p:DeleteExistingFiles=True
Take applications offline in IIS. Under \IIS Site\Web Site and \IIS Site\Web Site - Legacy, add files app_offline.htm (http://appoffline.appspot.com/).
Copying over of files will be up to the team. You may want to delete all current files from IIS or just cherrypick files, or copy over the build output. That would assume that no resource files were removed between releases, only changes to the dlls and configuration. Also, the tools and scripts can vary, for example, you may wish to use ROBOCOPY.
xcopy "C:\Pub\Web Site\*" "\\IIS Site\Web Site" /s /i /y
xcopy "C:\Pub\Web Site - Legacy\*" "\\IIS Site\Web Site - Legacy" /s /i /y
Copy the environment specific configuration files to the IIS Site Configuration folder (Hub.Legacy.appSettings.config and Hub.WebApp.appSettings.json). Ensure files are named correctly and are configured for the intended environment.
Remove (or rename) the 2 app_offline.htm files
Notes
DbServer
Name of the database server.
Value is always used to override what is set in ALL the connection strings for Hub.Legacy.
DbName
Name of the database. Default is Gcpe.Hub.
Value is always used to override what is set in ALL the connection strings for Hub.Legacy.
FaviconImg
Relative web path to .ico file to use as the favicon.
Allows graphic rebranding of site.
Example for BC: "~/Resources/BC/favicon.ico"
ContactsHeaderImg
Relative web path to image file placed in header of the Contacts / Media Relations DB application.
Allows graphic rebranding of site.
Example for BC: "~/Resources/BC/MediaRelations@2x.png"
CalendarLookAheadCoverImg
Physical file path to image used on Look Ahead Reports. File is added as the report is built.
Allows for graphic rebranding of site.
Example for BC: "\Resources\BC\LookAheadCover.png"
NewsHelpUrl
This is an absolute url to help pages for News.
Part of the path (the actual help file name) is passed in to build the absolute URL.
Value must have a placeholder for the page name.
ex. https://gcpe.gov.bc.ca/help/hub/Pages/{0}.aspx
LdapUrl
Url for your Active Directory (ex. LDAP://dmn.mygov/dc=dmn,dc=mygov)
ActiveDirectoryDomain
Domain Context or Domain name. (ex. dmn.mygov)
SMTPServer
Outbound mail server host.
LogMailFrom / LogMailTo
Email addresses used for sending error messages from Corporate Calendar.
ApplicationOwnerOrganizations
Comma separated list of Ministries (Abbreviation) considered the owners of the application.
Default: "GCPEHQ,GCPEMEDIA,PREM"
Application Owners (members of those Ministries) have more power within the applications. For example, they can see all ministries, have more fields on activities available.
Used to populate CustomPrincipal.IsInApplicationOwnerOrganizations
HQAdmin
Single Ministry designated as Head Quarters / Admin.
Default: "GCPEHQ"
Members of this ministry have more power and responsibility within the applications.
Used to populate CustomPrincipal.IsGCPEHQ
Version
Version number displayed on Corporate Calender
Currently set at version 8.
SharedWithExcludes
Comma separated list of ministries that will not appear on Activity "Shared across/with Ministry" selection list
HelpFileUri
Url to a help file (htm or pdf)
Used on Corporate Calendar Site.master page.
ShowSignificanceField / SignificanceIsRequired
Used in Corporate Calendar - Activity
Determine if significance field to be rendered and if it is required.
Field should only be required if it is shown.
ShowScheduleField / SchedulingIsRequired
Used in Corporate Calendar - Activity
Determine if schedule field to be rendered and if it is required.
Field should only be required if it is shown.
StrategyIsRequired
Used in Corporate Calendar - Activity
Determine if strategy field is required.
ShowHqCommentsField
Used in Corporate Calendar - Activity
Determine if Look Ahead Comments field is shown.
ShowRecordsSection
Used in Corporate Calendar - Activity
Determine if Records Section (associated release documents) are shown.
DisableEditTable
Disable Editing on Corporate Calender Admin screens.
SubscribeBaseUri
Url to the News On Demand Service. This service is not part of the Hub Open Source project.
Should match configuration in Hub.WebApp.appSettings.json
Used in Contacts / Media Relations Db application
DoExceptionLogging
Exceptions raised and thrown, or just logged
Boolean (true/false)
ContributorGroups
See Groups Configuration and Permissions Matrix
Comma Separated List of Active Directory groups used to determine Contributors
A User is considered a contributor if in one of these groups.
For add/edit company, add/edit contact
AdminGroups
See Groups Configuration and Permissions Matrix
Comma Separated List of Active Directory groups used to determine Admins
A User is considered a Admin if in one of these groups.
For add/edit company, add/edit contact
TypedownItemLimit
In Contacts / Media Relations, Limit the number of items in typedown list (ajax search results)
Integer, default 20
CompanyPurgeDays
In Contacts / Media Relations, remove deleted records older than this.
Integer, default 90
ContactPurgeDays
In Contacts / Media Relations, remove deleted records older than this.
Integer, default 90
LookBackDays
In Contacts / Media Relations, specify deleted record earliest date range (leave records for lookback).
Integer, default 10
PurgeTaskFrequencyHours
In Contacts / Media Relations, on session start, check to see if purge needs to be run.
Integer, default 24
DisableEmail
Set whether to disable emails from Contact / Media Relations
Boolean, default true
FromEmailAddress
Email address to use as the sender for Contact / Media Relations emails
MaxBccEmails
limit the number of bccs added to emails in Contact / Media Relations application.
Integer, default 30
permissions_N
See Groups Configuration and Permissions Matrix
CloudEndpointsProtocol / CloudAccountName / CloudAccountKey / CloudEndpointSuffix
Configuration for Cloud based services.
All values above are used to build the connection string:
DefaultEndpointsProtocol={CloudEndpointsProtocol};AccountName={CloudAccountName};AccountKey={CloudAccountKey};EndpointSuffix={CloudEndpointSuffix}
See (see LOCAL_MEDIA_STORAGE Preprocessor Symbol).
If LOCAL_MEDIA_STORAGE is not defined (the default), then the application expects cloud based storage for media assets for News Release (pictures etc), else it expects there be local storage (see MediaAssetsUnc)
NewsHostUri
URI for Gov News Host (not part of the Hub Open Source project)
This is where the published news releases are hosted/available.
MediaAssetsUri
URI for Media Assets on Gov News (not part of the Hub Open Source project).
PublishLocation
UNC or mapped drive for publishing artifacts.
DeployLocations
UNC or mapped drive(s) for deploying artifacts.
Comma separated list.
MediaAssetsUnc
UNC for Media Assets.
Used when LOCAL_MEDIA_STORAGE is defined.
DeployFolders
UNC for deploying Assets.
Comma separated list.
Used when LOCAL_MEDIA_STORAGE is defined.
NewsFileFolder
UNC for media asset manament.
Used when LOCAL_MEDIA_STORAGE is defined.
EnableForecastTab
Whether to show the Forecast Tab or not on News Release Management application.
Boolean, default is false
FlickrApiKey / FlickrApiSecret / FlickrApiToken / FlickrApiTokenSecret / FlickrApiVerifier / FlickrPrivateBaseUri
Configure private Flickr Account for pictures included with News Releases.
TrustedReverseProxyServers
Comma Separated list of Servers that we can mine for Site Minder headers
ex. SM_USER
Used in Authentication.
ValidationSettings:UnobtrusiveValidationMode
This setting is required by the Calendar Activity page.
You will get an error like the following without it: $(...).tooltip is not a function
Default value: "None"
Within the Media Relations / Contacts application (/Legacy/Contacts), Active Directory groups are used for additional logic and security.
See Active Directory User Groups
In the Hub.Legacy.appSettings.config, there are two group settings: ContributorGroups and AdminGroups.
These settings are comma separated lists of Active Directory Groups and are give special privileges for adding/editing Companies and Contacts, history of records. Admins are always considered Contributors. Admins can also edit things like web addresses and Media Distribution lists.
Active Directory groups are also used to build a permissions matrix for Media Relations / Contacts. In the Hub.Legacy.appSettings.config, there are a series of keys named permissions_NNN. The numbers are irrelevant, all keys beginning with permissions_ will be read to build out the matrix.
The matrix provides a mapping for groups to specific sections of the Media Relations / Contacts application and specific functionality.
The permissions_ key values are parsed into Site Sections, Active Directory Group, permissions.
Example:
<add key="permissions_1" value="MediaRelationsCompany/GCPE_CONTRIB/Read|Create|Update" />
The 3 components are separated with "/".
The permissions (or site actions) are separated with "|".
In the above:
Site Section = MediaRelationsCompany
Active Directory Group = GCPE_CONTRIB
Site Actions = Read, Create, Update.This means, that members of GCPE_CONTRIB Active Directory Group can read, create new, and update existing companies.
Enumeration used to define certain pages/screens within Media Relations (see Hub.Legacy/Gcpe.Contacts.Library/Permissions.cs).
Flags used to determine allowed functionality within the application; basically permissions (see Hub.Legacy/Gcpe.Contacts.Library/Permissions.cs).
Notes
SubscribeBaseUri
Url to the News On Demand Service. This service is not part of the Hub Open Source project.
In Hub.WebApp, the service is used to add subscribers to News On Demand.
Should match configuration in Hub.Legacy.appSettings.config
HQMinistry
The HQMinistry is the abbreviation of a Ministry designated as the head communications branch office.
By default, it is set to GCPEMEDIA.
This is used to determine which ministry and ministry contacts should receive the emailed End of Day Summary report.
NoReplyAddress
Email address used when sending End of Day summary report.
FaviconImg
Path to .ico file to use as the favicon.
Allows graphic rebranding of site.
Example for BC: "/resources/bc/favicon.ico"
ConnectionStrings / HubDbContext
Connection string to Gcpe.Hub database.
Connection string is used as entered in configuration, no substitutions or further building are done with this value.
Logging
Configure the NET Core logging.
See documentation for details.
MailProvider To send email, one of the following must be configured..
SearchService
Configuration of the Cloud based Media Request search service.
This is not required.