Flow Visual Git Diff enhancements + deploy notify documentation (#1008)

* Flow Visual Diff enhancements - Display full node fields table when it contains updated elements - Fix removed long links - Handle cases where Flow has been added or deleted * deploy:notify documentation * docgen * linter fixes * [Mega-Linter] Apply linters fixes :) --------- Co-authored-by: nvuillam <[email protected]>
hardisgroupcom · Jan 16, 2025 · d68e18c · d68e18c
1 parent d3191d1
commit d68e18c
Show file tree

Hide file tree

Showing 23 changed files with 446 additions and 60 deletions.
diff --git a/.github/linters/.cspell.json b/.github/linters/.cspell.json
@@ -113,6 +113,7 @@
         "MASTERLABEL",
         "MYFOLDER",
         "MYREPORTNAME",
+        "MYSTATUS",
         "MYTASK",
         "Metadatas",
         "NOPMD",
@@ -219,6 +220,7 @@
         "accordioninstance",
         "accordionlinter",
         "accordionlist",
+        "accordionmerge",
         "accordionmonitoring",
         "accordionms",
         "accordionnotifications",

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,14 @@
 
 Note: Can be used with `sfdx plugins:install sfdx-hardis@beta` and docker image `hardisgroupcom/sfdx-hardis@beta`
 
+## [5.15.5] 2025-01-16
+
+- Flow Visual Diff enhancements
+  - Display full node fields table when it contains updated elements
+  - Fix removed long links
+  - Handle cases where Flow has been added or deleted
+- Update [hardis:project:deploy:notify](https://sfdx-hardis.cloudity.com/hardis/project/deploy/notify/) documentation
+
 ## [5.15.4] 2025-01-15
 
 - Allow to disable calls to AI prompts API using DISABLE_AI=true

diff --git a/docs/commands.md b/docs/commands.md
@@ -32,9 +32,11 @@
 |:----------------------------------------------------------------------------|:------|
 | [**hardis:doc:extract:permsetgroups**](hardis/doc/extract/permsetgroups.md) |       |
 | [**hardis:doc:flow2markdown**](hardis/doc/flow2markdown.md)                 |       |
+| [**hardis:doc:mkdocs-to-salesforce**](hardis/doc/mkdocs-to-salesforce.md)   |       |
 | [**hardis:doc:packagexml2markdown**](hardis/doc/packagexml2markdown.md)     |       |
 | [**hardis:doc:plugin:generate**](hardis/doc/plugin/generate.md)             |       |
 | [**hardis:doc:project2markdown**](hardis/doc/project2markdown.md)           |       |
+| [**hardis:doc:project2markdown copy**](hardis/doc/project2markdown copy.md) |       |
 
 ## hardis:git
 

diff --git a/docs/hardis/doc/flow2markdown.md b/docs/hardis/doc/flow2markdown.md
@@ -4,6 +4,9 @@
 ## Description
 
 Generates a markdown documentation from a Flow file
+
+If [AI integration](https://sfdx-hardis.cloudity.com/salesforce-ai-setup/) is configured, documentation will contain a summary of the Flow.  
+
 
 ## Parameters
 

diff --git a/docs/hardis/doc/mkdocs-to-salesforce.md b/docs/hardis/doc/mkdocs-to-salesforce.md
@@ -0,0 +1,43 @@
+<!-- This file has been generated with command 'sf hardis:doc:plugin:generate'. Please do not update it manually or it may be overwritten -->
+# hardis:doc:mkdocs-to-salesforce
+
+## Description
+
+Generates MkDocs HTML pages and upload them to Salesforce as a static resource
+
+This command performs the following operations:
+
+- Generates MkDocs HTML pages (using locally installed mkdocs-material, or using mkdocs docker image)
+- Creates a Static Resource, a VisualForce page and a Custom Tab metadata
+- Upload the metadatas to the default org
+- Opens the Custom Tab in the default browser (only if not in CI context)
+
+Note: the documentation must have been previously generated using "sf hardis:doc:project2markdown --with-history"
+
+You can:
+
+- Specify the type of documentation to generate (CICD or Monitoring) using the --type flag. Default is CICD.
+- Override default styles by customizing mkdocs.yml
+
+More info on [Documentation section](https://sfdx-hardis.cloudity.com/salesforce-project-documentation/)
+
+
+## Parameters
+
+| Name              |  Type   | Description                                                   | Default | Required |       Options       |
+|:------------------|:-------:|:--------------------------------------------------------------|:-------:|:--------:|:-------------------:|
+| debug<br/>-d      | boolean | Activate debug mode (more logs)                               |         |          |                     |
+| flags-dir         | option  | undefined                                                     |         |          |                     |
+| json              | boolean | Format output as json.                                        |         |          |                     |
+| skipauth          | boolean | Skip authentication check when a default username is required |         |          |                     |
+| target-org<br/>-o | option  | undefined                                                     |         |          |                     |
+| type<br/>-t       | option  | Type of the documentation to generate. Default is "all"       |  CICD   |          | CICD<br/>Monitoring |
+| websocket         | option  | Websocket host:port for VsCode SFDX Hardis UI integration     |         |          |                     |
+
+## Examples
+
+```shell
+sf hardis:doc:mkdocs-to-salesforce
+```
+
+
diff --git a/docs/hardis/doc/packagexml2markdown.md b/docs/hardis/doc/packagexml2markdown.md
@@ -15,6 +15,7 @@ Generates a markdown documentation from a package.xml file
 | json              | boolean | Format output as json.                                                               |         |          |         |
 | outputfile<br/>-f | option  | Force the path and name of output report file. Must end with .md                     |         |          |         |
 | skipauth          | boolean | Skip authentication check when a default username is required                        |         |          |         |
+| target-org<br/>-o | option  | undefined                                                                            |         |          |         |
 | websocket         | option  | Websocket host:port for VsCode SFDX Hardis UI integration                            |         |          |         |
 
 ## Examples

diff --git a/docs/hardis/doc/project2markdown copy.md b/docs/hardis/doc/project2markdown copy.md
@@ -0,0 +1,74 @@
+<!-- This file has been generated with command 'sf hardis:doc:plugin:generate'. Please do not update it manually or it may be overwritten -->
+# hardis:doc:project2markdown copy
+
+## Description
+
+Generates a markdown documentation from a SFDX project
+
+- Package.xml files
+- Source Packages
+- sfdx-hardis configuration
+- Installed packages
+
+Can work on any sfdx project, no need for it to be a sfdx-hardis flavored one.
+
+Generates markdown files will be written in **docs** folder (except README.md where a link to doc index is added)
+
+To read Flow documentations if your markdown reader doesn't handle MermaidJS syntax, this command could require @mermaid-js/mermaid-cli
+
+- Run `npm install @mermaid-js/mermaid-cli --global` if puppeteer works in your environment
+- It can also be run as a docker image
+
+Both modes will be tried by default, but you can also force one of them by defining environment variable `MERMAID_MODES=docker` or `MERMAID_MODES=cli`
+
+_sfdx-hardis docker image is alpine-based and does not succeed to run mermaid/puppeteer: if you can help, please submit a PR !_
+
+If Flow history doc always display a single state, you probably need to update your workflow configuration:
+
+- on Gitlab: Env variable [`GIT_FETCH_EXTRA_FLAGS: --depth 10000`](https://github.com/hardisgroupcom/sfdx-hardis/blob/main/defaults/monitoring/.gitlab-ci.yml#L11)
+- on GitHub: [`fetch-depth: 0`](https://github.com/hardisgroupcom/sfdx-hardis/blob/main/defaults/monitoring/.github/workflows/org-monitoring.yml#L58)
+- on Azure: [`fetchDepth: "0"`](https://github.com/hardisgroupcom/sfdx-hardis/blob/main/defaults/monitoring/azure-pipelines.yml#L39)
+- on Bitbucket: [`step: clone: depth: full`](https://github.com/hardisgroupcom/sfdx-hardis/blob/main/defaults/monitoring/bitbucket-pipelines.yml#L18)
+
+![Screenshot flow doc](https://github.com/hardisgroupcom/sfdx-hardis/raw/main/docs/assets/images/screenshot-flow-doc.jpg)
+
+![Screenshot project documentation](https://github.com/hardisgroupcom/sfdx-hardis/raw/main/docs/assets/images/screenshot-project-doc.jpg)
+
+![Screenshot project documentation](https://github.com/hardisgroupcom/sfdx-hardis/raw/main/docs/assets/images/screenshot-project-doc-2.jpg)
+
+## Doc HTML Pages
+
+To read the documentation as HTML pages, run the following code (you need [**Python**](https://www.python.org/downloads/) on your computer)
+
+```python
+pip install mkdocs-material mdx_truly_sane_lists
+mkdocs serve
+```
+
+To just generate HTML pages that you can host anywhere, run `mkdocs build`
+
+
+
+## Parameters
+
+| Name         |  Type   | Description                                                         | Default | Required | Options |
+|:-------------|:-------:|:--------------------------------------------------------------------|:-------:|:--------:|:-------:|
+| debug<br/>-d | boolean | Activate debug mode (more logs)                                     |         |          |         |
+| diff-only    | boolean | Generate documentation only for changed files (used for monitoring) |         |          |         |
+| flags-dir    | option  | undefined                                                           |         |          |         |
+| json         | boolean | Format output as json.                                              |         |          |         |
+| skipauth     | boolean | Skip authentication check when a default username is required       |         |          |         |
+| websocket    | option  | Websocket host:port for VsCode SFDX Hardis UI integration           |         |          |         |
+| with-history | boolean | Generate a markdown file with the history diff of the Flow          |         |          |         |
+
+## Examples
+
+```shell
+sf hardis:doc:project2markdown
+```
+
+```shell
+sf hardis:doc:project2markdown --with-history
+```
+
+
diff --git a/docs/hardis/doc/project2markdown.md b/docs/hardis/doc/project2markdown.md
@@ -36,30 +36,39 @@ If Flow history doc always display a single state, you probably need to update y
 
 ![Screenshot project documentation](https://github.com/hardisgroupcom/sfdx-hardis/raw/main/docs/assets/images/screenshot-project-doc-2.jpg)
 
+If it is a sfdx-hardis CI/CD project, a diagram of the branches and orgs strategy will be generated.
+
+![](https://github.com/hardisgroupcom/sfdx-hardis/raw/main/docs/assets/images/screenshot-doc-branches-strategy.jpg)
+
+If [AI integration](https://sfdx-hardis.cloudity.com/salesforce-ai-setup/) is configured, documentation will contain a summary of the Flow.
+
+If you have a complex strategy, you might need to input property **mergeTargets** in branch-scoped sfdx-hardis.yml file to have a correct diagram.
+
 ## Doc HTML Pages
 
-To read the documentation as HTML pages, run the following code (you need python on your computer)
+To read the documentation as HTML pages, run the following code (you need [**Python**](https://www.python.org/downloads/) on your computer)
 
 ```python
-pip install mkdocs-material mdx_truly_sane_lists
-mkdocs serve
+pip install mkdocs-material mdx_truly_sane_lists || python -m pip install mkdocs-material mdx_truly_sane_lists || py -m pip install mkdocs-material mdx_truly_sane_lists
+mkdocs serve || python -m mkdocs serve || py -m mkdocs serve
 ```
 
-To just generate HTML pages that you can host anywhere, run `mkdocs build`
+To just generate HTML pages that you can host anywhere, run `mkdocs build || python -m mkdocs build || py -m mkdocs build`
 
 
 
 ## Parameters
 
-| Name         |  Type   | Description                                                         | Default | Required | Options |
-|:-------------|:-------:|:--------------------------------------------------------------------|:-------:|:--------:|:-------:|
-| debug<br/>-d | boolean | Activate debug mode (more logs)                                     |         |          |         |
-| diff-only    | boolean | Generate documentation only for changed files (used for monitoring) |         |          |         |
-| flags-dir    | option  | undefined                                                           |         |          |         |
-| json         | boolean | Format output as json.                                              |         |          |         |
-| skipauth     | boolean | Skip authentication check when a default username is required       |         |          |         |
-| websocket    | option  | Websocket host:port for VsCode SFDX Hardis UI integration           |         |          |         |
-| with-history | boolean | Generate a markdown file with the history diff of the Flow          |         |          |         |
+| Name              |  Type   | Description                                                         | Default | Required | Options |
+|:------------------|:-------:|:--------------------------------------------------------------------|:-------:|:--------:|:-------:|
+| debug<br/>-d      | boolean | Activate debug mode (more logs)                                     |         |          |         |
+| diff-only         | boolean | Generate documentation only for changed files (used for monitoring) |         |          |         |
+| flags-dir         | option  | undefined                                                           |         |          |         |
+| json              | boolean | Format output as json.                                              |         |          |         |
+| skipauth          | boolean | Skip authentication check when a default username is required       |         |          |         |
+| target-org<br/>-o | option  | undefined                                                           |         |          |         |
+| websocket         | option  | Websocket host:port for VsCode SFDX Hardis UI integration           |         |          |         |
+| with-history      | boolean | Generate a markdown file with the history diff of the Flow          |         |          |         |
 
 ## Examples
 

diff --git a/docs/hardis/org/monitor/backup.md b/docs/hardis/org/monitor/backup.md
@@ -38,6 +38,8 @@ This command is part of [sfdx-hardis Monitoring](https://sfdx-hardis.cloudity.co
 
 [Doc generation (including visual flows)](https://sfdx-hardis.cloudity.com/hardis/doc/project2markdown/) is triggered at the end of the command.
 
+If you want to also upload HTML Documentation on your Salesforce Org as static resource, use variable **SFDX_HARDIS_DOC_DEPLOY_TO_ORG="true"**
+
 If Flow history doc always display a single state, you probably need to update your workflow configuration:
 
 - on Gitlab: Env variable [`GIT_FETCH_EXTRA_FLAGS: --depth 10000`](https://github.com/hardisgroupcom/sfdx-hardis/blob/main/defaults/monitoring/.gitlab-ci.yml#L11)

diff --git a/docs/hardis/org/user/activateinvalid.md b/docs/hardis/org/user/activateinvalid.md
@@ -31,11 +31,11 @@ sf hardis:org:user:activateinvalid
 ```
 
 ```shell
-sf hardis:org:user:activateinvalid --target-org myuser@myorg.com
+sf hardis:org:user:activateinvalid --target-org my-user@myorg.com
 ```
 
 ```shell
-sf hardis:org:user:activateinvalid --profiles 'System Administrator,MyCustomProfile' --target-org myuser@myorg.com
+sf hardis:org:user:activateinvalid --profiles 'System Administrator,MyCustomProfile' --target-org my-user@myorg.com
 ```
 
 
diff --git a/docs/hardis/org/user/freeze.md b/docs/hardis/org/user/freeze.md
@@ -33,7 +33,7 @@ sf hardis:org:user:freeze
 ```
 
 ```shell
-sf hardis:org:user:freeze --target-org myuser@myorg.com
+sf hardis:org:user:freeze --target-org my-user@myorg.com
 ```
 
 ```shell

diff --git a/docs/hardis/org/user/unfreeze.md b/docs/hardis/org/user/unfreeze.md
@@ -33,7 +33,7 @@ sf hardis:org:user:unfreeze
 ```
 
 ```shell
-sf hardis:org:user:unfreeze --target-org myuser@myorg.com
+sf hardis:org:user:unfreeze --target-org my-user@myorg.com
 ```
 
 ```shell

diff --git a/docs/hardis/project/audit/apiversion.md b/docs/hardis/project/audit/apiversion.md
@@ -3,24 +3,41 @@
 
 ## Description
 
-Audit API version
+This command detects metadatas whose apiVersion is lower than parameter --minimumapiversion
+
+  It can also fix the apiVersions with the latest one, if parameter --fix is sent
+
+  Example to handle [ApexClass / Trigger & ApexPage mandatory version upgrade](https://help.salesforce.com/s/articleView?id=sf.admin_locales_update_api.htm&type=5) :
+
+   `sf hardis:project:audit:apiversion --metadatatype ApexClass,ApexTrigger,ApexPage --minimumapiversion 45.0 --fix`
+
 
 ## Parameters
 
-| Name                     |  Type   | Description                                                   | Default | Required | Options |
-|:-------------------------|:-------:|:--------------------------------------------------------------|:-------:|:--------:|:-------:|
-| debug<br/>-d             | boolean | Activate debug mode (more logs)                               |         |          |         |
-| failiferror<br/>-f       | boolean | Fails (exit code 1) if an error is found                      |         |          |         |
-| flags-dir                | option  | undefined                                                     |         |          |         |
-| json                     | boolean | Format output as json.                                        |         |          |         |
-| minimumapiversion<br/>-m | option  | Minimum allowed API version                                   |   20    |          |         |
-| skipauth                 | boolean | Skip authentication check when a default username is required |         |          |         |
-| websocket                | option  | Websocket host:port for VsCode SFDX Hardis UI integration     |         |          |         |
+| Name                     |  Type   | Description                                                                                        | Default | Required | Options |
+|:-------------------------|:-------:|:---------------------------------------------------------------------------------------------------|:-------:|:--------:|:-------:|
+| debug<br/>-d             | boolean | Activate debug mode (more logs)                                                                    |         |          |         |
+| failiferror<br/>-f       | boolean | Fails (exit code 1) if an error is found                                                           |         |          |         |
+| fix                      | boolean | Fix ApiVersion on specified Metadata Types.                                                        |         |          |         |
+| flags-dir                | option  | undefined                                                                                          |         |          |         |
+| json                     | boolean | Format output as json.                                                                             |         |          |         |
+| metadatatype             | option  | Metadata Types to fix. Comma separated. Supported Metadata types: ApexClass, ApexTrigger, ApexPage |         |          |         |
+| minimumapiversion<br/>-m | option  | Minimum allowed API version                                                                        |   20    |          |         |
+| skipauth                 | boolean | Skip authentication check when a default username is required                                      |         |          |         |
+| websocket                | option  | Websocket host:port for VsCode SFDX Hardis UI integration                                          |         |          |         |
 
 ## Examples
 
 ```shell
 sf hardis:project:audit:apiversion
 ```
 
+```shell
+sf hardis:project:audit:apiversion --metadatatype ApexClass,ApexTrigger,ApexPage --minimumapiversion 45
+```
+
+```shell
+sf hardis:project:audit:apiversion --metadatatype ApexClass,ApexTrigger,ApexPage --minimumapiversion 45 --fix
+```
+