Documentation fixes (#943)

Fixes #939
Fixes #921
Fixes #916
Fixes #904
Fixes #893
Fixes #885

---------

Co-authored-by: freddydk <freddydk@users.noreply.github.com>

Scenarios/EnableKeyVaultForAppSourceApp.md

@@ -1,7 +1,7 @@
 # #12 Enable KeyVault access for your AppSource App during development and/or tests
 For AppSource apps, if you want to enable KeyVault access for your app (as described [here](https://go.microsoft.com/fwlink/?linkid=2217058&clcid=0x409) you can add the access to this keyvault in your local development environment or your pipelines (for running tests) by adding 3 secrets to either the GitHub repo or your KeyVault. Based on [this walkthrough](https://go.microsoft.com/fwlink/?linkid=2216856&clcid=0x409) you will need to create 3 secrets:
-- A **KeyVaultClientId**, which is the Client ID for the AAD App with access to the KeyVault.
-- A **KeyVaultCertificateUrl**, pointing to a certificate which gives you access to the AAD App.
+- A **KeyVaultClientId**, which is the Client ID for the Microsoft Entra application registration with access to the KeyVault.
+- A **KeyVaultCertificateUrl**, pointing to a certificate which gives you access to the Microsoft Entra application registration.
 - A **KeyVaultCertificatePassword**, which is the password for this certificate.
 
 In the case of KeyVault access for apps, it is not enough to just add the secrets, you will also have to add information in the **.AL-Go\settings.json** that this app uses this KeyVault. Add these three settings

Scenarios/GetStarted.md

@@ -12,6 +12,10 @@
 ![Clone](https://github.com/microsoft/AL-Go/assets/10775043/84b92edb-72b8-4444-908c-0c6f6bc2b7f7)
 1. Start **VS Code**, press **Ctrl+Shift+P** and select **Git Clone**, paste the clone URL and select a folder in which you want to clone the directory.
 1. **Open the cloned repository** and **open the workspace** when VS Code asks you (or do it manually)
+
+> [!NOTE]
+> You can rename the `al.code-workspace` file to `<anothername>.code-workspace` to be able to better distinguish the workspaces.
+
 1. In the **.AL-Go** folder, choose the **localDevEnv.ps1** script and Run the PowerShell script.
 ![LocalDevEnv](https://github.com/microsoft/AL-Go/assets/10775043/fded935a-b529-4ade-8daa-bbe7e37726b8)
 1. Answer the questions asked about container name, authentication mechanism, credentials and select none for license file. The script might show a dialog asking for permissions to run docker commands, select **Yes** in this dialog. Wait for completion of the script.

Scenarios/RegisterProductionEnvironment.md

@@ -1,5 +1,5 @@
 # #5 Register a customer production environment for Manual Deployment
-*Prerequisites: A completed [scenario 4](CreateRelease.md), an online production environment setup for S2S as specified in task 2 here [Using Service to Service Authentication - Business Central | Microsoft Docs](https://go.microsoft.com/fwlink/?linkid=2217415&clcid=0x409), using the same AAD App as scenario 3*
+*Prerequisites: A completed [scenario 4](CreateRelease.md), an online production environment setup for S2S as specified in task 2 here [Using Service to Service Authentication - Business Central | Microsoft Docs](https://go.microsoft.com/fwlink/?linkid=2217415&clcid=0x409), using the same Microsoft Entra application registration as scenario 3*
 
 ***Note**: For access to environments, environment secrets, and deployment branches in private or internal repositories, you must use GitHub Pro, GitHub Team, or GitHub Enterprise. (see [this](https://go.microsoft.com/fwlink/?linkid=2216857&clcid=0x409)). We are considering adding a secondary option for listing environments.*
 1. Following the process in step 3, you can add an environment to the GitHub repository under settings called **MYPROD (Production)**, which maps to a production environment called **MYPROD**. Remember the **AUTHCONTEXT** Secret. Apps will NOT be deployed to production environments from the CI/CD pipeline, by adding the **(Production)** tag, the environment will be filtered out already during the **Analyze** phase. You need to run the **Publish To Environment** workflow to publish the apps. Leave the App version as **current**, which means that the **latest released bits** are published to **MYPROD**.

Scenarios/RegisterSandboxEnvironment.md

@@ -1,11 +1,11 @@
 # #3 Register a customer sandbox environment for Continuous Deployment using S2S
-*Prerequisites: A completed [scenario 2](AddATestApp.md), an AAD App, and an online sandbox environment called QA with the setup for S2S as specified in task 1 and 2 [here](https://go.microsoft.com/fwlink/?linkid=2217415&clcid=0x409) completed. You will also need the `BcContainerHelper PowerShell` module installed on your computer.*
+*Prerequisites: A completed [scenario 2](AddATestApp.md), an Microsoft Entra application registration, and an online sandbox environment called QA with the setup for S2S as specified in task 1 and 2 [here](https://go.microsoft.com/fwlink/?linkid=2217415&clcid=0x409) completed.
 
 ***Note**: For access to environments, environment secrets, and deployment branches in private or internal repositories, you must use GitHub Pro, GitHub Team, or GitHub Enterprise. (see [this](https://go.microsoft.com/fwlink/?linkid=2216857&clcid=0x409)). We are considering adding a secondary option for listing environments.*
 1. On github.com, open **Settings** and **Environments** in your project. Click **New Environment** and specify the **name of the environment** you have created in your tenant.
 ![Add Environment](https://github.com/microsoft/AL-Go/assets/10775043/ec3d7bf3-84dd-4ca4-8c6c-b79d796afadf)
 1. Under **Environment secrets**, choose the **Add Secret** action. Create a secret called **AUTHCONTEXT**, and enter a **COMPRESSED JSON** construct with 3 values: TenantID (where the environment lives), ClientID, and ClientSecret (from the pre-requisites), like:
-`{"TenantID":"<TenantID>","ClientID":"<theClientID>","ClientSecret":"<theClientSecret>"}`
+`{"TenantID":"<TenantID>","ClientID":"<theClientID>","ClientSecret":"<theClientSecret>"}`. 
 ![Add Environment](https://github.com/microsoft/AL-Go/assets/10775043/79d41d03-7b94-4876-a44b-a4276473147a)
 1. Navigate to **Actions**, select the **Publish To Environment** workflow and choose **Run workflow**. Enter **latest** in the **App version** field and the **name of your environment** or keep the * in the **environment to receive the new version** field. Click **Run workflow**.
 ![Add Environment](https://github.com/microsoft/AL-Go/assets/10775043/f207e06b-451d-4e31-8938-2c72f14c2527)

Scenarios/SelfHostedGitHubRunner.md

@@ -28,12 +28,15 @@ GitHub runners can be registered for an organization (accessible for all reposit
    - GIT (getbuildagent use `choco install git --force --params "/NoAutoCrlf"` after installing choco using `https://chocolatey.org/install.ps1`))
    - 7zip (getbuildagent use `choco install 7zip`)
    - GitHub CLI (getbuildagent use `choco install gh`)
-   - PowerShell 7 (getbuildagent use `choco install pwsh -y`)
+   - PowerShell 7.4.1 (getbuildagent use `choco install pwsh -y`)
    - Microsoft Visual C++ Redistributable for Visual Studio 2015-2022 14.36.32532 (getbuildagent use `choco install vcredist140 -y`)
    - Microsoft .NET (getbuildagent use `choco install dotnet -y`)
    - Microsoft .NET SDK (getbuildagent use `choco install dotnet-sdk -y`)
    - nuget.org added as dotnet nuget source (getbuildagent use `dotnet nuget add source https://api.nuget.org/v3/index.json --name nuget.org`)
 
+> [!NOTE]
+> If the Deploy Reference Documentation job results in an error like [this](https://github.com/actions/upload-pages-artifact/issues/95), then you need to check your GIT installation as described in the issue.
+
 ## Allow your repository access to your runners
 1. On the list of Runners on GitHub, choose the runner group **Default** and allow public repositories if your repository is public.
 ![public](https://github.com/microsoft/AL-Go/assets/10775043/9bdd01ab-ac67-44bf-bfd1-af5c5ec91364)

Scenarios/settings.md

@@ -247,7 +247,7 @@ Here are the parameters to use in your custom script:
 | Parameter | Description | Example |
 | --------- | :--- | :--- |
 | `$parameters.type` | Type of delivery (CD or Release) | CD |
-| `$parameters.apps` | Apps to deploy | /home/runner/.../GHP-Common-main-Apps-2.0.33.0.zip |
+| `$parameters.apps` | Apps to deploy. This can either be an array of .zip files or .app files, or it can be an array of folders, containing apps or .zip files. You can use the `Copy-AppFilesToFolder` function to extract and copy all apps to one folder | /home/runner/.../GHP-Common-main-Apps-2.0.33.0.zip |
 | `$parameters.EnvironmentType` | Environment type | SaaS |
 | `$parameters.EnvironmentName` | Environment name | Production |
 | `$parameters.Branches` | Branches which should deploy to this environment (from settings) | main,dev |

Workshop/AddAnApp.md

@@ -37,9 +37,12 @@ Open the **Pull request** and click **Files changed** to see what the Pull reque
 |-|
 
 > [!NOTE]
-> The changes made by the workflow includes adding the new app path to the **al.code-workspace**, and adding an app folder with **app.json**, **HelloWorld.al** (sample code) and **.vscode/launch.json**.
+> The changes made by the workflow includes adding the new app path to the `al.code-workspace`, and adding an app folder with **app.json**, **HelloWorld.al** (sample code) and **.vscode/launch.json**.
 The **Create a new app** workflow doesn't do anything else than just adding these changes, no magic behind the scenes.
 
+> [!NOTE]
+> If you have renamed the `al.code-workspace` file to `<anothername>.code-workspace` to be able to better distinguish the workspaces, it will still be updated.
+
 Select **Conversation** and merge the pull request by clicking **Merge the pull request**, **Confirm merge** and then delete the temporary branch created for the pull request, by clicking **Delete branch**. Select **Actions** and see that a merge commit workflow was kicked off:
 
 | ![image](https://github.com/microsoft/AL-Go/assets/10775043/80b1c400-7ce2-4511-a9e2-febb7da9f171) |

Workshop/ContinuousDeployment.md

@@ -63,6 +63,15 @@ Opening the Business Central environment and navigating to **Extension Managemen
 ## Creating an AUTHCONTEXT that uses S2S
 For using **S2S**, you need to do some preparation first. Follow [this](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/automation-apis-using-s2s-authentication) description to setup a **Microsoft Entra application** and register it inside the **Business Central environment** you want to deploy to.
 
+> [!TIP]
+> The term "application" in the context of Microsoft Entra can cause some confusion. You create an application registration, and allow access to X resources through that application registration.
+>
+> The application registration is allowed to forward the access token obtained with these permissions to a set of URLs. Now the owner of the ClientID and the ClientSecret or certificate can now authenticate and obtain the permissions assigned to that app registration.
+>
+> The Microsoft Entra application registration is not tied to a specific Business Central app, customer, partner, vendor, person or purpose - it is up to the creator of the app registration to determine this. You can have one application registration, which you can use for various test purposes (many different apps), while having more purposefull application registrations for production.
+>
+> Secrets and certificates can be revoked (if compromised) and permissions can be changed - this indirect way of authentication does provide more security than a simple username/password, which everybody understands.
+
 Once this is done, you can then create an Authentication context secret by using this PowerShell line from a machine with the latest BcContainerHelper module installed:
 
 ```powershell

Workshop/Prerequisites.md

@@ -17,7 +17,7 @@ You will need:
   {
     "useCompilerFolder": true,
     "doNotPublishApps": true,
-    "artifact": "https://bcartifacts.azureedge.net/sandbox/23.0.12034.13450/us"
+    "artifact": "bcartifacts/sandbox/23.0.12034.13450/us/closest"
   }
 ```
 

Workshop/Projects.md

@@ -56,6 +56,9 @@ When the **Create a new app in [main]** workflow has completed, select **Pull re
 > 2. A new US.code-workspace was created as a workspace for this project
 > 3. An app was added under the US folder called mysolution.us
 
+> [!NOTE]
+> You can rename the `US.code-workspace` file to `<anothername>.code-workspace` to be able to better distinguish the workspaces.
+
 Go ahead click **Conversation**, **merge the pull request** and **delete** the temporary branch.
 
 You don't have to wait for the **CI/CD workflow** to complete, just go ahead and run the **Create a new app** again. This time with the following parameters:
@@ -117,12 +120,12 @@ Before running **Update AL-Go System Files** however, let's make some changes to
 |-|
 
 Open the repository (do not open the workspace) and perform the following changes:
-- in **DK/.AL-Go/settings.json**, add **"artifact": "https://bcartifacts.azureedge.net/sandbox/23.0.12034.13450/dk"**
+- in **DK/.AL-Go/settings.json**, add **"artifact": "bcartifacts/sandbox/23.0.12034.13450/dk/closest"**
 - in **DK/.AL-Go/settings.json**, change **country** to **"dk"**
 - in **DK/mysolution.dk/HelloWorld.al**, add DK to the pageextension name (i.e. CustomerListExt to **CustomerListExtDK**)
-- in **US/.AL-Go/settings.json**, add **"artifact": "https://bcartifacts.azureedge.net/sandbox/22.0.54157.55210/us"**
+- in **US/.AL-Go/settings.json**, add **"artifact": "bcartifacts/sandbox/22.0.54157.55210/us/closest"**
 - in **US/mysolution.ud/HelloWorld.al**, add US to the pageextension name (i.e. CustomerListExt to **CustomerListExtUS**)
-- in **W1/.AL-Go/settings.json**, add **"artifact": "https://bcartifacts.azureedge.net/sandbox/22.0.54157.55210/w1"**
+- in **W1/.AL-Go/settings.json**, add **"artifact": "bcartifacts/sandbox/22.0.54157.55210/w1/closest"**
 - in **W1/.AL-Go/settings.json**, change **country** to **"w1"**
 - in **W1/mysolution.w1/HelloWorld.al**, add W1 to the pageextension name (i.e. CustomerListExt to **CustomerListExtW1**)