Merge pull request #168 from Volt-MX-GO/ZASDRAPI-010725

Image link update
HCL-TECH-SOFTWARE · Jan 15, 2025 · 014d7ff · 014d7ff
2 parents d5fae0e + 0742381
commit 014d7ff
Show file tree

Hide file tree

Showing 48 changed files with 1,314 additions and 91 deletions.
diff --git a/docs/assets/images/svg/keepblockdiagram.svg b/docs/assets/images/svg/keepblockdiagram.svg
diff --git a/docs/howto/.pages b/docs/howto/.pages
@@ -5,6 +5,7 @@ nav:
     - IdP: IdP
     - Production: production
     - Database: database
+    - Management console: management
     - VoltMX: VoltMX
     - Code examples: codesamples
 
diff --git a/docs/howto/IdP/configuringAD.md b/docs/howto/IdP/configuringAD.md
@@ -1,8 +1,8 @@
-# Configure Azure Active Directory as IdP
+# Configure Microsoft Entra ID as IdP
 
 ## About this task
 
-The procedures guide you on configuring Azure Active Directory as an IdP. Azure Active Directory has its own ideas about JWT compatibility:
+The procedures guide you on configuring Microsoft Entra ID, formerly Azure Active Directory, as an IdP. Microsoft Entra ID has its own ideas about JWT compatibility:
 
 - The `aud` property is fixed to the ID of the application, not as commonly, the URL of the target system.
 - There is no `scope` property, but instead `scp` to describe the requested scopes.
@@ -11,7 +11,7 @@ The procedures guide you on configuring Azure Active Directory as an IdP. Azure
 
 ### Register an application
 
-1. Navigate to the [Azure Portal](https://portal.azure.com){: target="\_blank"} to login, and then select **App registrations**.
+1. Navigate to the [Azure Portal](https://portal.azure.com){: target="_blank"} to login, and then select **App registrations**.
 
       ![Azure landing page](../../assets/images/configuringAD-01.png)
 
@@ -175,7 +175,7 @@ All URLs are retrievable by accessing the _OpenID Connect_ metadata document, co
 
 ## Test the application
 
-1. Go to [Downloads](../../references/downloads.md#azure-ad), and then download the `AzureTester.zip` file.
+1. Go to [Downloads](../../references/downloads.md#microsoft-entra-id-formerly-azure-active-directory), and then download the `AzureTester.zip` file.
 
     The file contains an [expressJS](https://expressjs.com/) application and related static files (HTML/CSS/JS).
 

diff --git a/docs/howto/IdP/index.md b/docs/howto/IdP/index.md
@@ -8,7 +8,7 @@ Topics to guide you in completing goals and tasks about Identity Provider in rel
 
 - [Configure Domino REST API to Use an OIDC Provider](configureoidc.md)
 
-- [Configure Azure Active Directory as IdP](configuringAD.md)
+- [Configure Microsoft Entra ID as IdP](configuringAD.md)
 
 - [Configure certificates](configuringCertificates.md)
 
@@ -18,3 +18,5 @@ Topics to guide you in completing goals and tasks about Identity Provider in rel
 
 - [Configure Domino REST API as SAML identity provider](keepsaml.md)
 
+- [Set up External IdP for Office Round Trip Experience](roundtripidp.md)
+
diff --git a/docs/howto/production/roundtripidp.md → docs/howto/IdP/roundtripidp.md b/docs/howto/production/roundtripidp.md → docs/howto/IdP/roundtripidp.md
diff --git a/docs/howto/index.md b/docs/howto/index.md
@@ -22,8 +22,16 @@ Considerations for production deployments, security included
 
 ## [Database](database/index.md)
 
-Working with databases, enable and configure for REST access
+Working with databases, and enabling and configuring for REST access
+
+## [Management console](management/index.md)
+
+Tasks requiring access to the Management console
 
 ## [VoltMX](VoltMX/index.md)
 
 Topics around the VoltMX integration of the REST API
+
+## [Code examples](codesamples/index.md)
+
+Code samples to interact with Domino REST API 
diff --git a/docs/howto/install/.pages b/docs/howto/install/.pages
@@ -2,7 +2,6 @@ nav:
     - index.md
     - Installation and configuration: tutorial/installconfig/index.html
     - symlink.md
-    - checksettings.md
     - modifyconfig.md
     - notesclient.md
     - uninstall.md

diff --git a/docs/howto/install/index.md b/docs/howto/install/index.md
@@ -8,8 +8,6 @@ Topics to guide you in completing goals and tasks related to installation, confi
 
 - [Create symlink for Domino 14 and Domino REST API](symlink.md)
 
-- [Check Domino REST API settings](checksettings.md)
-
 - [Modify configuration of Domino REST API](modifyconfig.md)
 
 - [Deploy to HCL Notes Client](notesclient.md)

diff --git a/docs/howto/install/modifyconfig.md b/docs/howto/install/modifyconfig.md
@@ -9,7 +9,7 @@ The procedure guides you on how to modify the Domino REST API configuration. Be
 1. Identify the configuration entries that you want to modify.
 
     !!!tip
-        To check Domino REST API settings, see [Check Domino REST API settings](checksettings.md).
+        To check Domino REST API settings, see [Check Domino REST API settings](../management/checksettings.md).
 
 2. Create a JSON file and include the configuration entries that you want to modify with the new values.
 

diff --git a/docs/howto/install/checksettings.md → docs/howto/management/checksettings.md b/docs/howto/install/checksettings.md → docs/howto/management/checksettings.md
diff --git a/docs/howto/production/configsrc.md → docs/howto/management/configsrc.md b/docs/howto/production/configsrc.md → docs/howto/management/configsrc.md
@@ -2,7 +2,7 @@
 
 ## About this task
 
-You can [check the Domino REST API settings via the **Config** tab](../install/checksettings.md) in the **Management console**. The **Config** tab shows you all the default configuration of the Domino REST API and all the additional configuration made using the JSON files saved in the `keepconfig.d` directory. This procedure guides you on how to identify the source files of all the configuration parameters that you see in the **Config** tab by using the **Config src** tab.
+You can [check the Domino REST API settings via the **Config** tab](../management/checksettings.md) in the **Management console**. The **Config** tab shows you all the default configuration of the Domino REST API and all the additional configuration made using the JSON files saved in the `keepconfig.d` directory. This procedure guides you on how to identify the source files of all the configuration parameters that you see in the **Config** tab by using the **Config src** tab.
 
 ## Before you begin
 

diff --git a/docs/howto/production/disablemodule.md → docs/howto/management/disablemodule.md b/docs/howto/production/disablemodule.md → docs/howto/management/disablemodule.md
@@ -1,7 +1,17 @@
 # Disable and enable module in production
 
+## About this task
+
 If your specific configuration entry or references suggest that there are variables or function in the `config.json` file, you may be able to change them.
 
+## Before you begin
+
+You must have access to the **Management console**.
+
+!!! note
+     - Make sure the **Management console** is secure. For more information, see [Functional Accounts](../../references/functionalUsers.md).
+     - Credentials for the **Management console** aren't managed by the configured IdP, but are derived from the [configuration of functional accounts](../../references/functionalUsers.md).
+
 ## Procedure
 
 1. Log in into the Management console (Port 8889).

diff --git a/docs/howto/management/index.md b/docs/howto/management/index.md
@@ -0,0 +1,16 @@
+# Management console
+
+--8<-- "future.md"
+
+Topics to guide you in completing goals and tasks about Domino REST API requiring access to the Management console:
+
+- [Check Domino REST API settings](checksettings.md)
+- [Find configuration sources](configsrc.md)
+- [Disable and enable module in production](disablemodule.md)
+- [JWT multi server](jwtmultiserver.md)
+- [Release suspended users](suspendeduser.md)
+- [Identify known users with valid JWT token](usersmc.md)
+
+
+
+
diff --git a/docs/howto/management/jwtmultiserver.md b/docs/howto/management/jwtmultiserver.md
@@ -0,0 +1,33 @@
+# JWT Multi-Server
+
+The API uses JWT Bearer tokens for verification, but because the access tokens come from different token servers, the validation of the tokens needs to be changed. 
+
+## Before you begin
+
+You must have access to the **Management console**.
+
+!!! note
+     - Make sure the **Management console** is secure. For more information, see [Functional Accounts](../../references/functionalUsers.md).
+     - Credentials for the **Management console** aren't managed by the configured IdP, but are derived from the [configuration of functional accounts](../../references/functionalUsers.md).
+
+## Procedure
+
+1. Login into the Management console (Port 8889).
+
+2. Type a name you want to call this certificate into the **Certificate Name**. No spaces or special characters.
+
+    - for example: MultiDomain
+
+3. Click **Create IdP certificate**.
+
+    Domino REST API generates 4 files in this server's `[notesdata]/keepconfig.d` directory:
+
+    - MultiDomain.cert.pem
+    - MultiDomain.json
+    - MultiDomain.private.key.pem
+    - MultiDomain.public.key.pem
+
+5. Copy these 4 files to your other Domino servers into the `[notesdata]/keepconfig.d` directory.
+6. Restart Domino REST API on all servers with this new configuration and now share the same JWT keys.
+
+
diff --git a/docs/howto/production/suspendeduser.md → docs/howto/management/suspendeduser.md b/docs/howto/production/suspendeduser.md → docs/howto/management/suspendeduser.md
diff --git a/docs/howto/production/usersmc.md → docs/howto/management/usersmc.md b/docs/howto/production/usersmc.md → docs/howto/management/usersmc.md
diff --git a/docs/howto/production/.pages b/docs/howto/production/.pages
@@ -1,22 +1,18 @@
 nav:
     - index.md
     - changefilesize.md
-    - prodports.md
-    - customAPI.md
-    - disablemodule.md
+    - Configure ports: prodports.md
+    - Customize API schemas and endpoints: customAPI.md
     - dominohttps.md
-    - configsrc.md
     - hardening.md
     - httpsprod.md
-    - usersmc.md
-    - jwtmultiserver.md
+    - Host SPA with ReactJS: reactjs.md
     - configparam.md
-    - suspendeduser.md
     - roundtrip.md
     - virtualsheet.md
-    - roundtripidp.md
-    - signencrypt.md
-    - versionupdate.md
+#    - roundtripidp.md
+    - Set up for encryption, decryption, signing: signencrypt.md
+    - Update Domino REST API: versionupdate.md
 
 
 
diff --git a/docs/howto/production/dominohttps.md b/docs/howto/production/dominohttps.md
@@ -1,4 +1,4 @@
-# Enable HTTPS using the Domino Certificate Manager
+# Enable HTTPS using Domino Certificate Manager
 
 !!!note
     This feature is only available starting from the Domino REST API v1.1.0 release. 

diff --git a/docs/howto/production/index.md b/docs/howto/production/index.md
@@ -14,25 +14,17 @@ Topics to guide you in completing configuration goals and tasks in relation to d
 
 - [Customize available API schemas and endpoints](customAPI.md)
 
-- [Disable modules](disablemodule.md)
-
 - [Enable HTTPS using Domino Certificate Manager](dominohttps.md)
 
-- [Find configuration sources](configsrc.md)
-
 - [Hardened production setup](hardening.md)
 
-- [Identify known users with valid JWT token](usersmc.md)
-
-- [JWT multi server](jwtmultiserver.md)
-
-- [Release suspended users](suspendeduser.md)
+- [Host SPA in Domino REST API with ReactJS](reactjs.md)
 
 - [Set up Office Round Trip Experience](roundtrip.md)
 
 - [Set up Virtual Spreadsheet](virtualsheet.md)
 
-- [Set up External IdP for Office Round Trip Experience](roundtripidp.md)
+<!-- [Set up External IdP for Office Round Trip Experience](roundtripidp.md)-->
 
 - [Set up Domino REST API for encryption, decryption, and signing](signencrypt.md)
 

diff --git a/docs/howto/production/jwtmultiserver.md b/docs/howto/production/jwtmultiserver.md
diff --git a/docs/howto/codesamples/reactjs.md → docs/howto/production/reactjs.md b/docs/howto/codesamples/reactjs.md → docs/howto/production/reactjs.md
@@ -1,23 +1,21 @@
-# ReactJS
+# Host SPA in Domino REST API with ReactJS
+<!--# ReactJS-->
 
-The Domino REST API allows to host [SPA](https://en.wikipedia.org/wiki/Single-page_application) in its `keepweb.d` directory. This page will highlight the steps to make this work with [ReactJS](https://react.dev).
+The Domino REST API allows hosting [SPA](https://en.wikipedia.org/wiki/Single-page_application) in its `keepweb.d` directory. This page highlights the procedure to make this work with [ReactJS](https://react.dev).
 
 !!! warning "This is not a ReactJS tutorial"
 
-    When you are not familiar with ReactJS, this is not the place for you.
-    Rather, learn [open standards](https://www.webcomponents.org), but if you insist:
+    When you are not familiar with ReactJS, this is not the place for you. Rather, learn [open standards](https://www.webcomponents.org). But if you insist, check these [tutorials](https://www.google.com/search?q=react+tutorial+2023).
 
-    [Google tutorials](https://www.google.com/search?q=react+tutorial+2023)
+## Before you begin
 
-## Prerequisites
+- You are familiar with [ReactJS](https://react.dev).
 
-- You are familiar with [ReactJS](https://react.dev)
+- You have installed NodeJS and ReactJs CLI.
 
-- NodeJS and ReactJs CLI installed
+## Procedure
 
-## Steps
-
-In the steps below, the name of the application (and thus the folder name) will be `mydominoreact`. Each application needs its own name, so replace `mydominoreact` with the name of your choice. Following web conventions, use lowercase characters and nothing special in the name (especially no spaces or slashes in any direction).
+In the steps below, the name of the application, and thus the folder name, will be `mydominoreact`. Each application needs its own name, so replace `mydominoreact` with the name of your choice. Following web conventions, use lowercase characters and nothing special in the name, especially no spaces or slashes in any direction.
 
 1. To ensure proper path resolution, you need to add `PUBLIC_URL=/keepweb/mypromydominoreactject` parameter to `.env` file.
 
@@ -26,8 +24,8 @@ In the steps below, the name of the application (and thus the folder name) will
 
 2. Reconfigure React to use [HashRouter](https://reactrouter.com/en/main/router-components/hash-router) instead of [BrowserRouter](https://reactrouter.com/en/main/router-components/browser-router).
 
-3. Make sure that all links have %PUBLIC_URL% prefix (e.g. for favicon.ico it's <link rel="shortcut icon" href="%PUBLIC_URL%/favicon.ico">).
-4. Execute `npm run build` (or whatever build process you use).
+3. Make sure that all links have `%PUBLIC_URL%` prefix. For example, for favicon.ico, it's `<link rel="shortcut icon" href="%PUBLIC_URL%/favicon.ico">`.
+4. Execute `npm run build`, or whatever build process you use.
 5. Rename `build` folder to `mydominoreact` and copy to the `keepweb.d` folder on your Domino server. To avoid the rename step, you can alter your build script to directly build into `mydominoreact` by adding to the `.env` file the entry `BUILD_PATH='./mydominoreact'`.
 
 ## Let's connect

diff --git a/docs/index.md b/docs/index.md
@@ -8,9 +8,12 @@ hide:
 
 {{ variable.drapi }} provides a secure REST API with access to HCL Domino servers and databases while running on HCL Domino and HCL Notes on Windows, Linux, and Mac. Designed to re-establish Domino as a world class, modern, standards-compliant, cloud native and enterprise-level collaboration platform, it adds contemporary REST APIs to Notes and Domino, enabling a modern programming experience with the tools of your choice. For more information, see [Introducing Domino REST API](topicguides/introducingrestapi.md).
 
-![Domino REST API](assets/images/svg/DominoKeepAPI.svg)
+<span style="color:darkblue">*Click the topics in the image to learn more.*</span>
+
+<object type="image/svg+xml" data="assets/images/svg/keepblockdiagram.svg" width="90%">
+Open the <a href="assets/images/svg/keepblockdiagram.svg">overview</a>
+</object>
 
----
 
 ## What's new
 
@@ -31,15 +34,17 @@ hide:
     - For installation information, see [Installation and configuration](tutorial/installconfig/index.md).
 
     - For everything that admin needs to know, use the [Admin cheat sheet](references/admincheatsheet.md).
-    
+
     - Trouble running the Domino REST API? Use the [Troubleshooting guide](references/troubleshooting.md).
 
 ---
+
 !!! tip "Ol' Notes hands start here"
 
     Are you coming from a Notes client with a Domino server background? You never had to deal with certificates, JSON Web Token, multiple TCP ports, OAuth, and all the fancy new terms of a shiny new web world. We got you covered, read [the primer](topicguides/notesprimer.md) to get started
-    
+
 ---
+
 !!! info "API definitions now available"
 
     The OpenAPI definitions, rendering using [ReDoc](https://github.com/Redocly/redoc), are now [available in the References](references/openapidefinitions.md). **Depending on your server configuration, not all endpoints will be active.**

diff --git a/docs/references/.pages b/docs/references/.pages
@@ -10,6 +10,7 @@ nav:
   - hostingstatic.md
   - OpenAPI: openapidefinitions.md
   - accesscontrol.md
+  - Schema Components: schemacomponents
   - Using Domino REST API: usingdominorestapi
   - Using Web UI: usingwebui
   - Security: security
@@ -23,4 +24,3 @@ nav:
   - ofba.md
   - richtextension.md
   - deprecated.md
-
diff --git a/docs/references/downloads.md b/docs/references/downloads.md
@@ -58,9 +58,9 @@ The following scripts are for reference only. They have been superseded by the s
     - dataDir with the directory the Notes Data is located in
     - keepDir with the directory Domino REST API is located in
 
-## Azure AD
+## Microsoft Entra ID formerly Azure Active Directory
 
-[AzureTester.zip](../assets/downloads/AzureTester.zip) is a simple test application you run on a local http server to check if a registered App in Azure AD can be used as JWT provider for the Domino REST API.
+[AzureTester.zip](../assets/downloads/AzureTester.zip) is a simple test application you run on a local http server to check if a registered App in Microsoft Entra ID, formerly Azure Active Directory, can be used as JWT provider for the Domino REST API.
 
 !!!warning 
     This is for testing only. Do **NOT** use this code in production.
diff --git a/docs/references/parameters.md b/docs/references/parameters.md
@@ -157,7 +157,7 @@ This is the verticle for managing WebHandlers. `worker`, `threadPoolName`, `thre
 | kid             | String  | Stands for _key ID_ and is a hint indicating which key was used to secure the JWS.                                                                                              |
 | keyFile         | String  | Path to the JWT public key                                                                                                                                                      |
 | iss             | String  | Identifies the principal that issued the JWT. The value is a case-sensitive string containing a string or URI value.                                                            |
-| aud             | String  | Identifies the recipient that the JWT is intended for. When configuring Azure Active Directory as an IdP, the value of this parameter is the Application ID URI you configured. |
+| aud             | String  | Identifies the recipient that the JWT is intended for. When configuring Microsoft Entra ID, formerly Azure Active Directory, as an IdP, the value of this parameter is the Application ID URI you configured. |
 | ofba | [JWT OFBA parameters](#jwt-ofba-parameters) | Parameters for enabling this external IdP to use for OFBA. |
 
 ## JWT OFBA parameters
@@ -167,7 +167,7 @@ This is the verticle for managing WebHandlers. `worker`, `threadPoolName`, `thre
 | active             | Boolean          | Set to `true` to enable the use of external IdP in OFBA.                       |
 | client_id          | String           | External IdP client ID to use for OFBA.                                        |
 | scope              | Array of Strings | List of scope names to use for OFBA.                                           |
-| application_id_uri | String           | An optional property. Required when external IdP is **Azure**. End with a `/`. |
+| application_id_uri | String           | An optional property. Required when external IdP is **Microsoft Entra ID, formerly Azure Active Directory**. End with a `/`. |
 
 ## Remarks
 

diff --git a/docs/references/schemacomponents/.pages b/docs/references/schemacomponents/.pages
@@ -0,0 +1,5 @@
+nav:
+  - index.md
+  - formdefinitions.md
+  - viewdefinitions.md
+  - agentdefinitions.md