Feature/12524 minor documentation fixes (#67)

* Fixed up release documentation ordering * Updated Observability URLs to point to new release * Fixed issue with CTX shortcode not loading correctly * Updated supported Windows versions * Updated IIS versions and associated footnotes * Refined OAuth2 support definition for ApiGatewayBasicAuthUsername and ApiGatewayBasicAuthPassword
CortexIntelligentAutomation · Oct 19, 2023 · d1d323e · d1d323e
1 parent c6b8878
commit d1d323e
Show file tree

Hide file tree

Showing 47 changed files with 789 additions and 164 deletions.
diff --git a/content/en/blog/releases/2023.X/2023.9.md b/content/en/blog/releases/2023.X/2023.9.md
diff --git a/.../docs/2023.11/Tutorials/administration.md → ...023.11/Tutorials/Administration/_index.md b/.../docs/2023.11/Tutorials/administration.md → ...023.11/Tutorials/Administration/_index.md
@@ -5,10 +5,6 @@ description: "This section includes tutorials about administering the {{% ctx %}
 weight: 40
 ---
 
-# {{< param title >}}
-
-{{< param description >}}
-
 ## Managing role-based access control
 
 Shows how to manage role-based access control within Gateway, including assigning access and flow permissions.

diff --git a/...t/en/docs/2023.9/Tutorials/development.md → ...s/2023.11/Tutorials/Development/_index.md b/...t/en/docs/2023.9/Tutorials/development.md → ...s/2023.11/Tutorials/Development/_index.md
@@ -5,10 +5,6 @@ description: "This section includes tutorials about developing automation using
 weight: 30
 ---
 
-# {{< param title >}}
-
-{{< param description >}}
-
 ## Signing in and out of Gateway
 
 Shows how to sign in and out of {{% ctx %}} Gateway.

diff --git a/.../docs/2023.9/Tutorials/troubleshooting.md → ...23.11/Tutorials/Troubleshooting/_index.md b/.../docs/2023.9/Tutorials/troubleshooting.md → ...23.11/Tutorials/Troubleshooting/_index.md
@@ -5,10 +5,6 @@ description: "This section includes tutorials about troubleshooting the {{% ctx
 weight: 50
 ---
 
-# {{< param title >}}
-
-{{< param description >}}
-
 ## Errors when starting published flows
 
 When making requests to start published flows, you may encounter errors. The videos below will show you how to fix them.

diff --git a/content/en/docs/2023.11/_index.md b/content/en/docs/2023.11/_index.md
@@ -1,6 +1,6 @@
 ---
-title: "2023.9"
-linkTitle: "2023.9"
+title: "2023.11"
+linkTitle: "2023.11"
 description: "Product documentation for the {{% ctx %}} automation platform, including guides, tutorials and reference documentation."
-weight: 998
+weight: 995
 ---
diff --git a/...ting-started/cloud/add-observability-to-innovation/Grafana/import-dashboards.md b/...ting-started/cloud/add-observability-to-innovation/Grafana/import-dashboards.md
@@ -65,7 +65,7 @@ To do this, follow these steps for all default {{% ctx %}} Innovation dashboards
 1. [Try it Out][]
 
 [configured]: {{< url path="Cortex.GettingStarted.Cloud.AddObservabilityToInnovation.Grafana.SetupLoki.MainDoc" >}}
-[Grafana.Dashboards.zip]: {{< url path="GitHub.Cortex.Observability.2.0.0.GrafanaDashboardsZip" >}}
+[Grafana.Dashboards.zip]: {{< url path="GitHub.Cortex.Observability.2.0.1.GrafanaDashboardsZip" >}}
 [Grafana]: {{< url path="Cortex.GettingStarted.Cloud.AddObservabilityToInnovation.Grafana.SetupGrafana.MainDoc" >}}
 [Loki]: {{< url path="Cortex.GettingStarted.Cloud.AddObservabilityToInnovation.Grafana.SetupLoki.MainDoc" >}}
 [Try it Out]: {{< url path="Cortex.GettingStarted.Cloud.AddObservabilityToInnovation.Grafana.TryItOut.MainDoc" >}}
diff --git a/...ud/add-observability-to-innovation/Grafana/install-promtail/install-promtail.md b/...ud/add-observability-to-innovation/Grafana/install-promtail/install-promtail.md
@@ -27,4 +27,4 @@ This archive contains the `promtail-local-config.yaml` configuration file, [NSSM
 [NSSM]: {{< url path="NSSM.MainDoc" >}}
 [Prerequisites]: {{< url path="Cortex.GettingStarted.Cloud.AddObservabilityToInnovation.Grafana.Prerequisites.MainDoc" >}}
 [Promtail 2.5.0]:  {{< url path="Grafana.SelfManaged.Downloads.Promtail.PromtailInstallZip" >}}
-[Promtail Install.zip]: {{< url path="GitHub.Cortex.Observability.2.0.0.PromtailInstallZip" >}}
+[Promtail Install.zip]: {{< url path="GitHub.Cortex.Observability.2.0.1.PromtailInstallZip" >}}
diff --git a/.../getting-started/cloud/add-observability-to-innovation/Grafana/prerequisites.md b/.../getting-started/cloud/add-observability-to-innovation/Grafana/prerequisites.md
@@ -21,7 +21,7 @@ The application servers must have internet access in order to communicate with t
 
 | Server Role        | Windows Server[^1]                             | Other Software     |
 |--------------------|------------------------------------------------|--------------------|
-| Application Server | [2019 (x64)][] *Recommended*<br>[2016 (x64)][] | [Promtail 2.5.0][] |
+| Application Server | [2022 (x64)][] *Recommended*<br>[2019 (x64)][] | [Promtail 2.5.0][] |
 
 [^1]: Windows Server Standard and Datacenter editions are supported. Filesystem **must be NTFS** and networking **must use IPv4**. Linux is not supported, but may be in the future.
 
@@ -52,8 +52,8 @@ A domain user which is a member of the Local Administrators group on all Applica
 
 1. [Set up Grafana][]
 
-[2016 (x64)]: {{< url path="Microsoft.Downloads.Windows.Server2016" >}}
 [2019 (x64)]: {{< url path="Microsoft.Downloads.Windows.Server2019" >}}
+[2022 (x64)]: {{< url path="Microsoft.Downloads.Windows.Server2022" >}}
 [Architecture]: {{< url path="Cortex.GettingStarted.Cloud.AddObservabilityToInnovation.Grafana.Architecture.MainDoc" >}}
 [Set up Grafana]: {{< url path="Cortex.GettingStarted.Cloud.AddObservabilityToInnovation.Grafana.SetupGrafana.MainDoc" >}}
 [Promtail 2.5.0]:  {{< url path="Grafana.SelfManaged.Downloads.Promtail.PromtailInstallZip" >}}
diff --git a/...n-to-72/multiple-server-with-ha/install-application-and-loadbalancer-servers.md b/...n-to-72/multiple-server-with-ha/install-application-and-loadbalancer-servers.md
@@ -12,9 +12,9 @@ This guide describes how to install the Application Servers and Load Balancer Se
 ## Make Installation Artefacts Available
 
 1. Choose one of the Application Servers to be used for installation, and copy the following artefacts to a folder on it:
-   * Cortex Innovation {{< version >}} - Block Packages.zip
-   * Cortex Innovation {{< version >}} - App Services.zip
    * Cortex Innovation {{< version >}} - App Server Install Scripts.zip
+   * Cortex Innovation {{< version >}} - App Services.zip
+   * Cortex Innovation {{< version >}} - Block Packages.zip
 
 1. Extract the `Cortex Innovation {{< version >}} - App Server Install Scripts.zip` file to a folder with the same name.
 
@@ -218,8 +218,8 @@ To avoid answering all of the prompts `-Override 0` can be added to the end of t
     |----------------------------------------------|-------------|
     |`AppServicesPath`                              | Configure this value with the location of the Application Services zip file on the Application Server used for installation. |
     |`BlockPackagesPath`                           | Configure this value with the location of the Block Packages zip file on the Application Server used for installation. |
-    |`ApiGatewayBasicAuthUsername`                     | Configure this value with the username that will be used for Basic Authentication when making HTTPS requests to the API Gateway Service (e.g. starting production flows).<br /><br />For security reasons it is recommended that the default value `BasicAuthUser` should be changed.<br /><br />Currently only Basic Authentication using a single user is supported, OAuth2 will be supported in a future release.<br /><br />This value will be needed [later, when upgrading Gateway][Upgrade Gateway]. |
-    |`ApiGatewayBasicAuthPassword`                      | Configure this value with the password that will be used for Basic Authentication when making HTTPS requests to the API Gateway Service (e.g. starting production flows). <br /><br />This password should be [{{% ctx %}} Encrypted][CORTEX Encrypted]. For security reasons it is recommended that the default value `ADA9883B11BD4CDC908B8131B57944A4` should be changed. <br /><br />This value will be needed [later, when upgrading Gateway][Upgrade Gateway].|
+    |`ApiGatewayBasicAuthUsername`                     | Configure this value with a username that can be used to make HTTPS requests to the API Gateway Service using Basic Authentication (e.g. starting flows). This username will be used by Gateway for all HTTPS requests to the API Gateway Service.<br /><br />For security reasons it is recommended that the default value `BasicAuthUser` should be changed.<br /><br />This value will be needed [later, when upgrading Gateway][Upgrade Gateway].<br /><br /> This username can also be used by external services for HTTPS requests to the API Gateway Service but is not recommended; these requests should use an OAuth2 session for an authorised Active Directory user.|
+    |`ApiGatewayBasicAuthPassword`                      | Configure this value with the password for the username specified for `ApiGatewayBasicAuthUsername`.<br /><br />This password should be [{{% ctx %}} Encrypted][CORTEX Encrypted]. For security reasons it is recommended that the default value `ADA9883B11BD4CDC908B8131B57944A4` should be changed. <br /><br />This value will be needed [later, when upgrading Gateway][Upgrade Gateway].|
     |`CustomerName`                                | A name identifying the platform being installed. This must have no spaces or symbols. It will be appended to the node names that are displayed in Service Fabric Explorer. |
     |`ApplicationServerIPv4Addresses`              | The IPv4 addresses of the Application Servers. The first of these must be the Application Server used for installation. |
     |`LoadBalancerServerIPv4Address`               | The IPv4 address of the Load Balancer Server. This is only needed if using the built-in load balancer. |

diff --git a/.../add-innovation-to-72/multiple-server-with-ha/install-web-application-server.md b/.../add-innovation-to-72/multiple-server-with-ha/install-web-application-server.md
@@ -34,6 +34,33 @@ We recommend that the single-node Service Fabric instance, used by {{% ctx %}} G
 
 Ensure that a valid {{% ctx %}} licence file named `Cortex.lic` exists on the Web Application server, in the location `%ProgramData%\Cortex\Licences`. If it does not, follow the instructions located at [Licensing Requirements][].
 
+### Grant folder permissions to the {{% ctx %}} Gateway Application Pool User
+
+The following folders require `Modify` permission to allow creating the `NuGet` folders and its `NuGet.Config` file within:
+
+* `C:\Windows\System32\config\systemprofile\AppData\Roaming`
+* `C:\Windows\SysWOW64\config\systemprofile\AppData\Roaming`
+
+For each folder, perform the following steps:
+
+1. Navigate to the `AppData` folder.
+1. Right-click on the `Roaming` folder and click `Properties`.
+1. In the dialog, click the `Security` tab.
+1. Check the `Application Pool` user for Gateway is listed in the `Group or user names` and has `Modify` permissions.
+1. If the `Application Pool` user for Gateway is not listed:
+   1. Click the `Edit...` button.
+   1. Click the `Add...` button.
+   1. Enter the username of the application pool user and click `OK`.
+   1. In the `Permissions` section at the bottom, check `Modify`.
+   1. Click `OK`.
+   1. Click `Yes` to change the permission to the folder.
+1. If the `Application Pool` user for Gateway is listed but does not have permissions:
+   1. Click the `Edit...` button.
+   1. Select the `Application Pool` user.
+   1. Check `Modify`.
+   1. Click `OK`.
+   1. Click `Yes` to change the permission to the folder.
+
 ### Certificate Requirements
 
 In order to ensure that the correct certificate is used during the upgrade of {{% ctx %}} Gateway, it is necessary to [assign a friendly name][Assign Certificate Friendly Name] to the certificate that is currently being used for {{% ctx %}} Gateway. It is important to set the `ImportCertificate` parameter to `$false` when [configuring the {{% ctx %}} Gateway installation script][Configure CORTEX Gateway Installation Script].
@@ -148,7 +175,59 @@ To install the components required for debugging, perform the steps detailed in
     If the errors do not give any instructions on how to rectify, please contact [{{% ctx %}} Service Portal][CORTEX Service Portal] for further assistance.
 
 1. Once the PowerShell script execution has completed, a prompt will appear to restart the machine.  You can choose to restart now (`N`) or later (`L`).
-1. The {{% ctx %}} Gateway website will now be available on `<protocol>://<host>:<port>/<webapplicationname>`, e.g. `https://localhost/gateway`.
+1. In a browser, navigate to the {{% ctx %}} Gateway website, available at `<protocol>://<host>:<port>/<webapplicationname>`, e.g. `https://localhost/gateway` and wait for the login page to load.
+
+### Grant additional folder permissions to the {{% ctx %}} Gateway Application Pool User
+
+#### Cortex Blocks Provider Host folder
+
+Check that the {{% ctx %}} Gateway `Application Pool` user has rights to the `Cortex Blocks Provider Host folder` folder using the following steps:
+
+1. Navigate to `C:\ProgramData\Cortex`
+1. Right-click on the `Cortex Blocks Provider Host` folder and click `Properties`.
+1. In the dialog, click the `Security` tab.
+1. Check the `Application Pool` user for Gateway is listed in the `Group or user names` and has `Modify` permissions.
+1. If the `Application Pool` user for Gateway is not listed:
+   1. Click the `Edit...` button.
+   1. Click the `Add...` button.
+   1. Enter the username of the application pool user and click `OK`.
+   1. In the `Permissions` section at the bottom, check `Modify`.
+   1. Click `OK`.
+1. If the `Application Pool` user for Gateway is listed but does not have permissions:
+   1. Click the `Edit...` button.
+   1. Select the `Application Pool` user.
+   1. Check `Modify`.
+   1. Click `OK`.
+
+#### Repo folder
+
+Check that the {{% ctx %}} Gateway `Application Pool` user has rights to the `Repo` folder using the following steps:
+
+1. Check where the `Repo` folder is located
+   1. Navigate to the `gateway` IIS folder (usually `%SystemDrive%\inetpub\wwwroot\Cortex\gateway`, e.g. `C:\inetpub\wwwroot\Cortex\gateway`)
+   1. Open the `web.config` file.
+   1. Find the value of the `connectionString` named `CortexRepositories`
+1. Navigate to the `Repo` folder, not opening it.
+1. Right-click on the `Repo` folder and click `Properties`.
+1. In the dialog, click the `Security` tab.
+1. Check the `Application Pool` user for Gateway is listed in the `Group or user names` and has `Modify` permissions.
+1. If the `Application Pool` user for Gateway is not listed:
+   1. Click the `Edit...` button.
+   1. Click the `Add...` button.
+   1. Enter the username of the application pool user and click `OK`.
+   1. In the `Permissions` section at the bottom, check `Modify`.
+   1. Click `OK`.
+1. If the `Application Pool` user for Gateway is listed but does not have permissions:
+   1. Click the `Edit...` button.
+   1. Select the `Application Pool` user.
+   1. Check `Modify`.
+   1. Click `OK`.
+
+#### Perform an IIS reset
+
+1. Open a Windows PowerShell (x64) window as administrator.
+1. Run the following command: `iisreset`.
+1. Wait for the action to complete.
 
 ## Preserve installation files
 

diff --git a/...tarted/on-premise/add-innovation-to-72/multiple-server-with-ha/prerequisites.md b/...tarted/on-premise/add-innovation-to-72/multiple-server-with-ha/prerequisites.md
@@ -172,9 +172,9 @@ To enable  Network Discovery and File Sharing:
 
 On the Web Application Server and each Application Server, the following Windows Services must be running:
 
+* Performance Logs & Alerts
 * Remote Registry
 * Windows Event Log
-* Performance Logs & Alerts
 
 ## Security Requirements
 

diff --git a/...ise/add-innovation-to-72/single-server-without-ha/install-application-server.md b/...ise/add-innovation-to-72/single-server-without-ha/install-application-server.md
@@ -12,9 +12,9 @@ This guide describes how to install the Application Server components on the ser
 ## Make Installation Artefacts Available
 
 1. Copy the following artefacts to a folder on the server:
-   * Cortex Innovation {{< version >}} - Block Packages.zip
-   * Cortex Innovation {{< version >}} - App Services.zip
    * Cortex Innovation {{< version >}} - App Server Install Scripts.zip
+   * Cortex Innovation {{< version >}} - App Services.zip
+   * Cortex Innovation {{< version >}} - Block Packages.zip
 
 1. Extract the `Cortex Innovation {{< version >}} - App Server Install Scripts.zip` file to a folder with the same name.
 
@@ -171,8 +171,8 @@ To avoid answering all of the prompts `-Override 0` can be added to the end of t
     |----------------------------------------------|-------------|
     |`AppServicesPath`                              | Configure this value with the location of the App Services zip file on the server. |
     |`BlockPackagesPath`                           | Configure this value with the location of the Block Packages zip file on the server. |
-    |`ApiGatewayBasicAuthUsername`                 | Configure this value with the username that will be used for Basic Authentication when making HTTPS requests to the API Gateway Service (e.g. starting production flows). <br /><br />Currently only Basic Authentication using a single user is supported, OAuth2 will be supported in a future release.<br /><br />This value will be needed [later, when upgrading Gateway][Upgrade Gateway]. |
-    |`ApiGatewayBasicAuthPassword`                      | Configure this value with the password that will be used for Basic Authentication when making HTTPS requests to the API Gateway Service (e.g. starting production flows). This should be [{{% ctx %}} Encrypted][CORTEX Encrypted]. <br /><br />This value will be needed [later, when upgrading Gateway][Upgrade Gateway].|
+    |`ApiGatewayBasicAuthUsername`                     | Configure this value with a username that can be used to make HTTPS requests to the API Gateway Service using Basic Authentication (e.g. starting flows). This username will be used by Gateway for all HTTPS requests to the API Gateway Service.<br /><br />For security reasons it is recommended that the default value `BasicAuthUser` should be changed.<br /><br />This value will be needed [later, when upgrading Gateway][Upgrade Gateway].<br /><br /> This username can also be used by external services for HTTPS requests to the API Gateway Service but is not recommended; these requests should use an OAuth2 session for an authorised Active Directory user.|
+    |`ApiGatewayBasicAuthPassword`                      | Configure this value with the password for the username specified for `ApiGatewayBasicAuthUsername`.<br /><br />This password should be [{{% ctx %}} Encrypted][CORTEX Encrypted]. For security reasons it is recommended that the default value `ADA9883B11BD4CDC908B8131B57944A4` should be changed. <br /><br />This value will be needed [later, when upgrading Gateway][Upgrade Gateway].|
     |`CustomerName`                                | A name identifying the platform being installed. This must have no spaces or symbols. It will be appended to the node names that are displayed in Service Fabric Explorer. |
     |`ApplicationServerIPv4Addresses`              | The IPv4 address of the server.|
     |`ServerCertificatePath`                       | The local path of a .PFX certificate file on the server. Environment variables cannot be used. <br /><br />This is only needed if installing with CA Certificates (Recommended). The certificate should meet the [Certificate Requirements][]. <br /><br />This certificate will be used for: <ul><li>Securing communication between the Application Services.</li><li>Allowing Application Services to identify themselves to clients such as Gateway.</li><li>Preventing unauthorised nodes from joining the single node cluster.</li><li>Connecting to Service Fabric Explorer from each of the Application Servers.</li></ul>{{< alert type="warning" title="Warning" >}}It is critical to set a reminder to {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.Advanced.RolloverCertificates" title="update certificates" >}} in good time before they expire. If they expire then the platform will cease to function and {{< ahref path="Cortex.ServicePortal.MainDoc" title="CORTEX Service Portal" >}} must be contacted for support.{{< /alert >}}|
@@ -253,10 +253,6 @@ More advanced configuration (such as changing ports) can be undertaken by modify
 
     If the errors do not give any instructions on how to rectify, see [Troubleshooting During Installation][] for further information; if this does not help then please contact [{{% ctx %}} Service Portal][CORTEX Service Portal] for assistance.
 
-## Check Application Services
-
-{{< section "/install-application-server/check-application-services/single-server.md">}}
-
 ## Add Read and Execute access to Windows Crypto folder  
 
 Service Fabric requires access to the `C:\ProgramData\Microsoft\Crypto\` folder for the `Network Service` users.
@@ -274,6 +270,10 @@ icacls "C:\ProgramData\Microsoft\Crypto\*" /grant *S-1-5-20:RX /t
 Some files might fail to be processed with `Access is denied`. This can be ignored.
 {{% /alert %}}
 
+## Check Application Services
+
+{{< section "/install-application-server/check-application-services/single-server.md">}}
+
 ## Preserve installation files
 
 Ensure that the installation files are backed up or kept on the server, especially the scripts and config files that have been modified. This will make it easier to perform further actions in future, such as troubleshooting, certificate rollover, uninstallation, reinstallation and updates.