intranet/README.md

# Overview
An overhaul of J.V. Manufacturing's corporate Intranet page.  
This site combines links & services from the previous intranet site with portals to access ticket repositories from old SpiceWorks On-prem helpdesks. 
## Features
* Quick access links for useful sites & documents
* Portals accessing historical tickets from Request & Sales helpdesks
* PHP rewrite of the J.V. Safety Quiz
## Platform
Based on Symfony 6.3.3, a php framework for developing web applications.  
It is cross-platform compatible, and can be run on Windows or Linux servers.
# Install
## (Optional, Recommended) Configuring Git
The recommended way to manage the app is through version-control software, such as Git. Git is recommended as it greatly simplifies continuous integration/development and provides a robust system for managing application versions.  
This section will detail how to set up Git SCM for Windows.

### Understanding Git
Imagine our repository as a tree. The trunk is our ‘origin’, or master upstream branch, from which everything branches off. 
Each ‘branch’ in the tree organizes groups of changes to the origin. The leaves on these branches represent individual changes to files. A leaf may be a change to a specific line, or a whole new file.
#### Definitions
**Git:** Version-control software used frequently to track history & manage changes to files. Most commonly used in software development.  
**Working Tree:** A tree-graph of changes made to tracked files.  
**Tracked files:** any file that is being monitored by Git.  
**Branch:** Collections of changes. Branches may have branches of their own, which can each contain differing versions of the same file.  
**Merge:** The process of merging changes from one branch to another.  
**Remote:** A repository other than the local that changes are synced to. A local repo may have multiple remotes.  
**Upstream:** Typically refers to an item on the remote that the local copy is based on.  
**Downstream:** Refers to items that are based on this. The production & development clones are all downstream from the Remote.  
**Commit:** The process where changes are applied to a repository.  
**Push:** Commits are copied (pushed) TO the upstream branch.  
**Pull:** Commits are copied (pulled) FROM the upstream branch and applied to files in the repository.
### Install Git
[Download Git SCM for Windows](https://gitforwindows.org/)<br>
Run the installer. Default settings are acceptable.

## Deployment
### Requirements:
-	Git must be installed on the host system. [See Server Setup – Install Git](#install-git) for instructions on installing.
### Deployment
1.	Open a terminal to the root of the C drive, or wherever the production code will reside.
2.	Use this following command to clone the upstream repository:
```bash
git clone ssh://[user]@jv[hostname/IP]://[aboslute_path_including_Symfony.git]
```
3.	Enter your password when prompted, and the repository should be cloned into /Symfony
4.	The tickets database is included in the clone, but attachments are not. The default and sales folders will need to be copied into Symfony/public/TicketAttachments manually. Failure to do so will result in broken attachments.
5.	In the project root find the file .env.prod and make a copy of it. Rename the copy to .env 
 - Look through the contents of .env and make sure these settings match your needs. Specifically, look at who will receive complaint emails

### IIS Configuration
https://learn.microsoft.com/en-us/iis/application-frameworks/scenario-build-a-php-website-on-iis/configuring-step-1-install-iis-and-php  
These instructions are based on Microsoft’s official documentation at the link above.
#### Prerequisites:
-	PHP 8.x.x
-	Composer, latest version
-	IIS with CGI
#### Installing PHP
[Download PHP](https://windows.php.net/download/)
You need the NON-THREAD-SAFE VERSION  
1.	Create a new folder in C:/php and extract the contents of the php zip there.
2.	In C:/php locate php.ini – production and rename it to php.ini
3.	Add C:/php to the system PATH variable
4.	Edit php.ini, find `;extension = php_openssl.dll` and remove the semicolon
5.	Repeat step 4 with the lines `extension = php_sqlite.dll` and `extension = php_sqlite3.dll`
6.	Save and close php.ini
#### Install Composer
[Download the Windows installer here](https://getcomposer.org/download/)  
If you haven’t yet added PHP to the PATH var, then do that first. After that’s done, just run the installer and install it for all users.
#### Install URL Rewrite 2 for IIS
[Get URL Rewrite here](https://download.microsoft.com/download/1/2/8/128E2E22-C1B9-44A4-BE2A-5859ED1D4592/rewrite_amd64_en-US.msi)  
Simply run the installer. IIS needs to be installed already. 
#### Configure IIS for PHP
Open IIS Manager. 
1.	Add a new website, name it something like Intranet. Make sure Symfony gets its own Application Pool.
2.	The physical path should route to the `public` folder inside the Symfony directory.
3.	The protocol should be HTTP on port 80. 
4.	Uncheck `Start Website Immediately` and click OK.
5.	In Connections select the new website and then open Handler Mappings
6.	Under Actions click Add Module Mapping  
a.	Request Path should be `*.php`  
b.	Module should be set to FastCgiModule  
c.	Executable should be set to the path to php-cgi.exe that was bundled with your PHP install.  
d.	Name can be FastCGI  
7.	Back in the Connections pane select the new website again. Then open URL Rewrite
8.	In the Actions pane, click Add Rules, under Inbound Rules select Blank rule and name the new rule File Request  
a.	Set the Pattern to `/(.*)`  
b.	Under Conditions, add 3 new rules  
i.	Change ‘Check if input string:’  to Is a File and click OK.  
ii.	Change ‘Check if input string:’ to Does Not Match the Pattern and set the Pattern to ‘.php’ without quotes. Enable Ignore case and click OK.  
iii.	Change ‘Check if input string:’ to Does Not Match the Pattern and set the Pattern to ‘.htm’ without quotes. Enable Ignore case and click OK.  
c.	Under Action, set Action Type to None  
d.	Under Action, enable Stop processing of subsequent rules  
e.	In Actions (on the right) click Apply and then Back to Rules  
9.	Repeat step 8, but configure the new rule as follows  
a.	Name: Symfony Routing  
b.	Pattern: `/(.*)`  
c.	Action: Rewrite  
d.	Rewrite URL: `/Index.php`  
10.	Recycle the Application Pool for the intranet website and test.
11.	(Optional) Prepare the site cache  
a.	Open a terminal into the web app folder (i.e. C:/Symfony)  
b.	Run: `php bin/console cache:warmup`  
 
### Final Deployment Considerations
-	Make sure the IIS user (ISUR or whatever the AppPoolIdentity is) has read & write privileges within the /var directory.
-	Make sure Symfony is not running in DEBUG mode (APP_DEBUG should not be true in env vars.)  

## Updating
When new code is pushed to the remote master, it can be synchronized using a simple command:
```bash
git pull
```
So long as best practices with Git are respected, and the remote is available, the production codebase should be updated to reflect the most recent version.
After this is done, open a terminal to the project root (where bin is located) and run these commands, in this order:
```bash
php bin/console cache:clear
php bin/console cache:pool:prune
php bin/console cache:warmup
```
If you don’t see any changes, then it’s possible that master is behind another branch containing the new code. If this is the case, you’ll need to merge that branch into master before pulling. 
Merging branches can get messy and complicated quickly to new Git users, so it will not be explained here. Best practice dictates no changes should ever be made directly to master so it is highly recommended to learn some Git basics before modifying any code.
# Content Management
Changing page contents is mostly handled within special configuration files. Changes made to these files are reflected immediately upon saving. 
If you’ve chosen to deploy using Git, it’s important to know that changes made to production files may be overwritten during the next pull if they’re not committed. See the section [Committing Changes to Git](##committing-changes-to-git) for advice on persisting these.

## Main page
Portal Content on the main page is generated from the `portalLinks.yaml` file in the `%project_dir%/config` folder.  
The file follows the structure in which the data will be rendered on the webpage. Links are separated into objects (cards on the webpage.) Cards and links render in the order they’re given in the YAML file.
### Creating Cards
Create a new line in `portalLinks.yaml` and indent it with 2 spaces. Type the UNIQUE title of the card and append a colon at the end. Save the file. An empty card will now be rendered when the page is loaded
  
 

### Creating Links
1.	Create a new line under the card you want the link to be contained in.
2.	Indent the new line with 5 spaces. Add a hyphen (dash) followed by another space.
3.	Paste this YAML onto the new line: 
```yaml
{ title: 'Example Link', url: '', disabled: false}
```
4.	Replace the placeholder values accordingly:  
a.	title: The text to be displayed  
b.	url: the path this should link to. If internal, relative is fine. If external, use the absolute URI.  
c.	disabled: Optional. If included and set to true, the button will be rendered but inactive.  
5.	Save the file. The changes should be visible the next time the homepage is loaded by a client.
 
 
 
## Message of the Day (MOTD)
 
The MOTD is a banner that is displayed at the top of every page. It’s great for making announcements to users, such as advising them of an issue or advertising a new feature.  
The message’s contents are read from the ‘MOTD’ environment variable. Changes to this value are visible immediately.  
If this value is blank, the MOTD will not be rendered.
## Safety Training Documents
Just like the main portal page, content on the Safety site as well as quiz questions are generated from YAML files.
### Creating Training Topics
#### Building the Page
Make a new file under `%project_dir%/templates/Training/Safety/Topics`. Name this file `[name].html.twig`. Filenames should be lowercase.
Each html.twig file should have HTML placed between html and body tags, as you would with any other webpage.  

> **Notice:** *Header and navbars are inserted by the controller during rendering. There is no need to manually add these elements.*

#### Serving Files
Any file (such as videos) placed in the web root (`%project_dir%/public`) can be served to users. Symfony will automatically generate links to these files.
1.	Place the file you want to serve in the public folder. Using a subdirectory in this location is encouraged.
2.	In the .html.twig file, determine where you want the link and define a code block by places 2 enclosed curly-brackets. {{ }}
3.	Inside of the brackets, type asset(‘someLinkHere.pdf’) Replace someLinkHere with the relative path to the file to serve from public
##### Example: video.mp4 is at ./public/videos/video.mp4
```twig
{{ asset(‘videos/video.mp4’) }}
```
So long as this file actually exists (and you remembered to save the .html.twig document) this code block will be replaced with a link to the file when the page is loaded.  
If this file exists but a 404 error is returned, then the filename may need to be changed to something IIS can recognize. Remove spaces and unusual characters from the file name. 
 
#### Adding the Link
With the page created, adding a new link is easy.
Navigate to `%project_dir%/config/safetyLinks.yaml` and edit the file in any text editor.
By default, this file is split into 3 sections, keyed by the name of the card. Figure out which card you want the new link on and make a new line under it following the example of the rest of the file.  
You may copy this YAML snippet as a starting point:
```YAML
    - { title: 'Link Title', url: 'somesubject', disabled: false}
```
**title:** This is what will be displayed as the text when a link is rendered  
**url:** This should be the FIRST PART of the filename of the html.twig file. If the full filename is ‘safetyFirst.html.twig’ then this value should be ‘safetyFirst’ case-sensitive.  
**disabled:** False by default. If set to true, the link will be rendered but will be inactionable.
  

## Safety Quiz – Managing Questions
The YAML file for this section is at `%project_dir%/config/SafetyQuiz.yaml`
 
The Safety Quiz supports multiple-choice questions, and allows for multiple correct answers.  There is no requirement for number of questions and options. 
### Object Structure
Each question/answer object is keyed by a unique string, such as Question_1, Q2, etc. This string does not get used by the quiz, so it doesn’t matter what this is.  
**Text:** The question itself. This is what the tester will see.  
**Choices:** Answer options for the question go here.   
	**Label:** The text that’s displayed to represent the selection  
	**Value:** A True/false determining if this is the correct answer or not.  
## Committing Changes to Git
Changes made to production code will have to be discarded before any updates can be pulled from the upstream repository that modify those changed files. In case the production repo has to be restored, these changes will also be lost unless they’re committed and pushed upstream.
In the interest of simplicity, this section will describe the process for committing changes directly to master. This goes against best practice, but will be fine for page config changes.

1.	Open a terminal to the project root. On production, this should be C:/Symfony
2.	Use the following commands to stage * changes, commit them, and push the changes upstream:

|Command	| Description |
| -------- | --------------------------------- |
| `git add [filename]` |	Instructs git to track the file at the specified relative path. Wildcards may be used |
| `git commit -m “[Commit Message]”` |	Commits changes to the current branch (likely master) with the provided message. Message should be a short description of changes. Example: ‘add sharepoint portal link’|
|`git pull` |	Pulls pending changes from upstream. ALWAYS do this before a push|
|`git push` |	Updates upstream origin with the changes made.|

##  Git – Reverting Changes
To restore production to the current upstream branch (undoing any changes made locally) use this command
```git
git restore
```
All changes that have not been committed will be discarded.